```text theme={null}
Set up the Refactron MCP server for yourself in this repository and prove it
works before you tell me it is done. Do the steps in order.
You are running in Codex CLI.
STEP 1 - Check the prerequisites.
Run `node --version`. Refactron needs Node.js 18 or newer. If it is older or
missing, stop and tell me.
Run `python3 --version`, then check that `pytest` and `coverage` are
importable. Coverage attestation is Python-only, and it is what makes a
coverage-backed SAFE verdict possible. Without it the server still runs and
still gates the change, but every verdict caps at UNPROVEN.
STEP 2 - Install the server.
Run `which refactron-mcp`, or `where refactron-mcp` on Windows. If it prints a
path, go to step 3. Otherwise install it:
npm install -g refactron
That puts two binaries on PATH: `refactron` (the CLI) and `refactron-mcp` (the
MCP server). If you cannot install globally, install nothing and use the npx
form in step 3 instead.
Do not use `pip install refactron` for this. The PyPI wrapper provides the
`refactron` command only. It does not ship `refactron-mcp`.
STEP 3 - Register the server.
Run:
codex mcp add refactron -- refactron-mcp
The `--` separator is required. Everything after it is the command Codex
launches; everything before it is Codex's own flags.
Codex uses TOML, not JSON. If you edit ~/.codex/config.toml by hand, the entry
is a table, and the prefix is `mcp_servers` with an underscore, not
`mcpServers`:
[mcp_servers.refactron]
command = "refactron-mcp"
args = []
tool_timeout_sec = 900
Set `tool_timeout_sec` either way, editing the table afterwards if you used
`codex mcp add`. Codex's default per-tool timeout has changed between releases,
and either value can be shorter than a real suite run. When it fires you get a
tool failure rather than the verdict you already paid for.
Without a global install, use this instead. The `-p` flag is required, because
`refactron-mcp` is a second binary of the `refactron` package and not a package
of its own:
[mcp_servers.refactron]
command = "npx"
args = ["-y", "-p", "refactron", "refactron-mcp"]
tool_timeout_sec = 900
Check for a duplicate [mcp_servers.refactron] table before you finish. Two of
them is a parse error, and Codex rejects the whole config.
STEP 4 - Reload.
Codex CLI picks the server up on the next session. If it does not appear in
step 5, tell me to restart `codex`.
STEP 5 - Confirm the tool is exposed.
Run:
codex mcp list
`refactron` appears with its launch command. `codex mcp get refactron` prints
the resolved entry, and both accept --json. Then start a session and ask for
the tool list.
If it is configured but never starts, check for `enabled = false` on the table.
That key disables a server without removing it.
You are looking for a server named `refactron` exposing exactly
ONE tool: `verify_change`.
If the server is connected but no tool appears, the handshake failed. Prove the
binary itself works by sending it one initialize request:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
A working server replies on one line with serverInfo.name "refactron". If that
works and the client still shows nothing, the fault is the config: check the
root key and check that the file parses.
STEP 6 - Prove it works with one real verification.
Do not skip this. A connected server is not a working server.
Pick one small source file that this project's test suite exercises. Propose a
real but behaviour-preserving edit to it: reorder the operands of a commutative
expression, rename a local variable, that kind of thing. One or two lines.
Do NOT write that edit to disk. Call verify_change with the proposal instead:
repoRoot the ABSOLUTE path to this repository
edits [{ "path": "",
"newContent": "" }]
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified rather than the installed
one. Use PYTHONPATH=src for a src layout.
Write the command in module form (`python3 -m pytest`), NOT as a
bare console script (`pytest`): a console script cannot be measured
on Windows or under pyenv, asdf and nix, and coverage then reports
that it could not be determined.
Verify the change BEFORE it exists on disk. The shadow tree is a copy of the
working tree, so if you write the change first and then pass a `git diff` of
it, the diff no longer applies and you get "diff did not apply (stale base?)"
back instead of a verdict.
Verification runs the whole test suite in a shadow copy, so it can take minutes
on a real project. That is the work, not a hang.
STEP 7 - Report, then stop.
Tell me:
- which file you wrote, or which command you ran
- the exact `verdict` and the exact `reason` from the response
- the value of `coverage.tool`: "coverage.py" means coverage was measured,
"none" means it was not
Apply nothing. The step 6 edit was a probe. Confirm with `git status` that the
working tree is exactly as dirty as you found it, and no more.
Do not describe a SAFE verdict as "correct", "proven", or "guaranteed". SAFE
means the project's own tests ran the changed code and stayed green. It
inherits exactly what those tests check, and a weak suite yields a weak SAFE.
```
Prefer to do it yourself? The rest of this page is the same setup by hand.
## The format is TOML, not JSON
Every other client on this list takes a JSON object keyed by server name. Codex takes a TOML table per server, and the table prefix is `mcp_servers` with an underscore, not `mcpServers`.
## Config location
| Scope | Path | Applies to |
| ------- | ------------------------------------------- | ------------------------------- |
| User | `~/.codex/config.toml` | Every project |
| Project | `.codex/config.toml` in the repository root | That project, once you trust it |
## Add it
The `codex mcp add` subcommand writes the entry for you and gets the TOML shape right:
```bash theme={null}
codex mcp add refactron -- refactron-mcp
```
The `--` separator is required. Everything after it is the command Codex launches; everything before it is Codex's own flags.
To write it by hand, add this table to `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.refactron]
command = "refactron-mcp"
args = []
tool_timeout_sec = 900
```
To pin the version and skip the global install:
```toml theme={null}
[mcp_servers.refactron]
command = "npx"
args = ["-y", "-p", "refactron", "refactron-mcp"]
tool_timeout_sec = 900
```
The `-p` flag is required. `refactron-mcp` is a second binary of the `refactron` package, not a package of its own.
## Set `tool_timeout_sec` yourself
Codex applies a per-tool timeout, and its default has changed between releases: the published config reference documents 60 seconds, while current builds use a longer one. Either number can be shorter than a real test suite, and `verify_change` runs your whole suite.
Set `tool_timeout_sec` explicitly to comfortably more than a full suite run. Without it, a slow project reports a tool failure that is really a client-side timeout, and you lose a verdict you had already paid for.
`startup_timeout_sec` is a separate key covering only process launch and the MCP handshake. The default is fine for this server, which starts in well under a second.
## Verify the connection
```bash theme={null}
codex mcp list
```
`refactron` appears in the list with its launch command. For the single entry, including the resolved config:
```bash theme={null}
codex mcp get refactron
```
Both accept `--json` if you want to read the entry from a script.
Then start a session and ask for the tool list. You are looking for one tool, `verify_change`, under `refactron`.
## Troubleshooting
* **The table name is wrong**: it is `[mcp_servers.refactron]`. A `[mcpServers.refactron]` table is silently a different, unused key. Codex does not warn you.
* **The server is configured but never starts**: check for `enabled = false` on the table. That key disables a server without removing it, and it is easy to leave behind.
* **`command not found` on launch**: run `which refactron-mcp`. If it prints nothing, run `npm install -g refactron`, or switch to the `npx` form above.
* **A project-scoped `.codex/config.toml` is ignored**: Codex reads project config only for a trusted project. Trust the directory, or move the entry to `~/.codex/config.toml`.
* **A verification fails after about a minute on a suite that takes longer**: that is `tool_timeout_sec`, not a verdict. Raise it.
* **Duplicate TOML tables**: two `[mcp_servers.refactron]` tables in one file is a parse error, and Codex rejects the whole config. If you ran `codex mcp add` after hand-editing, check for both.
## Remove it
```bash theme={null}
codex mcp remove refactron
```
# Cursor
Source: https://docs.refactron.dev/mcp/cursor
Add the Refactron MCP server to Cursor with a project .cursor/mcp.json or the global ~/.cursor/mcp.json.
Cursor reads MCP servers from a project file or a global one. The project file is the better default: it travels with the repository, so everyone on the team gets the same gate.
## Set it up with your agent
One prompt, written for Cursor to read rather than you. It installs the
server, registers it, reloads, and proves the tool works with a real
verification.
```text theme={null}
Set up the Refactron MCP server for yourself in this repository and prove it
works before you tell me it is done. Do the steps in order.
You are running in Cursor.
STEP 1 - Check the prerequisites.
Run `node --version`. Refactron needs Node.js 18 or newer. If it is older or
missing, stop and tell me.
Run `python3 --version`, then check that `pytest` and `coverage` are
importable. Coverage attestation is Python-only, and it is what makes a
coverage-backed SAFE verdict possible. Without it the server still runs and
still gates the change, but every verdict caps at UNPROVEN.
STEP 2 - Install the server.
Run `which refactron-mcp`, or `where refactron-mcp` on Windows. If it prints a
path, go to step 3. Otherwise install it:
npm install -g refactron
That puts two binaries on PATH: `refactron` (the CLI) and `refactron-mcp` (the
MCP server). If you cannot install globally, install nothing and use the npx
form in step 3 instead.
Do not use `pip install refactron` for this. The PyPI wrapper provides the
`refactron` command only. It does not ship `refactron-mcp`.
STEP 3 - Register the server.
Create `.cursor/mcp.json` in the repository root, root key "mcpServers". The
project file is the better default: it travels with the repository, so the
whole team gets the same gate. The global file is ~/.cursor/mcp.json.
{ "mcpServers": { "refactron": { "command": "refactron-mcp" } } }
Merge into the existing "mcpServers" object if the file already has servers.
Without a global install, use this instead. The `-p` flag is required, because
`refactron-mcp` is a second binary of the `refactron` package and not a package
of its own:
{ "mcpServers": { "refactron": { "command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"] } } }
STEP 4 - Reload.
Cursor reloads MCP servers on a toggle, not on file save.
You cannot do this yourself. Tell me to open Cursor Settings, then Tools &
Integrations, called MCP in older builds, and switch the `refactron` toggle off
and back on. Wait for me before you continue.
STEP 5 - Confirm the tool is exposed.
Ask me to confirm that `refactron` shows a green indicator in Cursor Settings
under Tools & Integrations, with one tool beneath it.
Tools are only available in Agent mode. Ask mode does not call tools at all, so
if you cannot see the tool, check the mode before you suspect the config.
You are looking for a server named `refactron` exposing exactly
ONE tool: `verify_change`.
If the server is connected but no tool appears, the handshake failed. Prove the
binary itself works by sending it one initialize request:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
A working server replies on one line with serverInfo.name "refactron". If that
works and the client still shows nothing, the fault is the config: check the
root key and check that the file parses.
STEP 6 - Prove it works with one real verification.
Do not skip this. A connected server is not a working server.
Pick one small source file that this project's test suite exercises. Propose a
real but behaviour-preserving edit to it: reorder the operands of a commutative
expression, rename a local variable, that kind of thing. One or two lines.
Do NOT write that edit to disk. Call verify_change with the proposal instead:
repoRoot the ABSOLUTE path to this repository
edits [{ "path": "",
"newContent": "" }]
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified rather than the installed
one. Use PYTHONPATH=src for a src layout.
Write the command in module form (`python3 -m pytest`), NOT as a
bare console script (`pytest`): a console script cannot be measured
on Windows or under pyenv, asdf and nix, and coverage then reports
that it could not be determined.
Verify the change BEFORE it exists on disk. The shadow tree is a copy of the
working tree, so if you write the change first and then pass a `git diff` of
it, the diff no longer applies and you get "diff did not apply (stale base?)"
back instead of a verdict.
Verification runs the whole test suite in a shadow copy, so it can take minutes
on a real project. That is the work, not a hang.
STEP 7 - Report, then stop.
Tell me:
- which file you wrote, or which command you ran
- the exact `verdict` and the exact `reason` from the response
- the value of `coverage.tool`: "coverage.py" means coverage was measured,
"none" means it was not
Apply nothing. The step 6 edit was a probe. Confirm with `git status` that the
working tree is exactly as dirty as you found it, and no more.
Do not describe a SAFE verdict as "correct", "proven", or "guaranteed". SAFE
means the project's own tests ran the changed code and stayed green. It
inherits exactly what those tests check, and a weak suite yields a weak SAFE.
```
Prefer to do it yourself? The rest of this page is the same setup by hand.
## Config location
| Scope | Path | Applies to |
| ------- | ------------------------------------------------------- | ---------------------- |
| Project | `.cursor/mcp.json` in the repository root | This project only |
| Global | `~/.cursor/mcp.json` (`%USERPROFILE%\.cursor\mcp.json`) | Every project you open |
## Add it
Create the file if it does not exist:
```bash theme={null}
mkdir -p .cursor
```
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "refactron-mcp"
}
}
}
```
To pin the version and skip the global install:
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"]
}
}
}
```
The `-p` flag is required. `refactron-mcp` is a second binary of the `refactron` package, not a package of its own.
## Verify the connection
Open **Cursor Settings** then **Tools & Integrations** (called **MCP** in older builds). `refactron` appears in the list with a green indicator and one tool beneath it: `verify_change`.
Then ask the agent in a Chat pane, with Agent mode selected:
```text theme={null}
List the tools you have from the refactron MCP server.
```
It should name `verify_change` and nothing else.
## Troubleshooting
* **The server shows red or `Client closed`**: Cursor could not launch the command. Run `which refactron-mcp`. If it prints nothing, run `npm install -g refactron`, or switch to the `npx` form above.
* **Nothing appears after saving**: Cursor reloads servers on a toggle, not on file save. Switch the `refactron` toggle off and on in the settings pane.
* **The tool exists but the agent never calls it**: tools are only available in Agent mode. Ask mode does not call tools. See [Make it verify, not just connect](/mcp/overview#make-it-verify-not-just-connect) for a rule that makes the agent verify on its own.
* **`repoRoot` errors**: the tool needs an absolute path. Tell the agent to pass the project's absolute path, not `.` and not a path relative to anything.
* **A verification takes minutes**: `verify_change` runs your real test suite in a shadow copy. Long is expected on a large suite.
# Gemini CLI
Source: https://docs.refactron.dev/mcp/gemini-cli
Add the Refactron MCP server to Gemini CLI with the gemini mcp add command or ~/.gemini/settings.json.
Gemini CLI reads MCP servers from `settings.json` under the root key `mcpServers`, the same shape Claude Desktop and Cursor use. There is a subcommand that writes the entry for you.
## Set it up with your agent
One prompt, written for Gemini CLI to read rather than you. It installs the
server, registers it, reloads, and proves the tool works with a real
verification.
```text theme={null}
Set up the Refactron MCP server for yourself in this repository and prove it
works before you tell me it is done. Do the steps in order.
You are running in Gemini CLI.
STEP 1 - Check the prerequisites.
Run `node --version`. Refactron needs Node.js 18 or newer. If it is older or
missing, stop and tell me.
Run `python3 --version`, then check that `pytest` and `coverage` are
importable. Coverage attestation is Python-only, and it is what makes a
coverage-backed SAFE verdict possible. Without it the server still runs and
still gates the change, but every verdict caps at UNPROVEN.
STEP 2 - Install the server.
Run `which refactron-mcp`, or `where refactron-mcp` on Windows. If it prints a
path, go to step 3. Otherwise install it:
npm install -g refactron
That puts two binaries on PATH: `refactron` (the CLI) and `refactron-mcp` (the
MCP server). If you cannot install globally, install nothing and use the npx
form in step 3 instead.
Do not use `pip install refactron` for this. The PyPI wrapper provides the
`refactron` command only. It does not ship `refactron-mcp`.
STEP 3 - Register the server.
Run:
gemini mcp add refactron refactron-mcp
That defaults to PROJECT scope and writes `.gemini/settings.json` in whatever
directory you run it from. Add `--scope user` for ~/.gemini/settings.json
instead.
By hand, the root key is "mcpServers" and `timeout` is in MILLISECONDS:
{ "mcpServers": { "refactron": { "command": "refactron-mcp",
"timeout": 900000 } } }
900 would mean 0.9 seconds and every call would fail instantly. Gemini CLI
defaults to 600000, the same order as Refactron's own 600 second test gate, so
set it above the slowest full run of this suite.
Without a global install, use this instead. The `-p` flag is required, because
`refactron-mcp` is a second binary of the `refactron` package and not a package
of its own:
{ "mcpServers": { "refactron": { "command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"],
"timeout": 900000 } } }
STEP 4 - Reload.
Gemini CLI picks the server up on the next session. If it does not appear in
step 5, tell me to restart `gemini`.
STEP 5 - Confirm the tool is exposed.
Run:
gemini mcp list
`refactron` should show as Connected. Inside a session, `/mcp` shows connected
servers with their tools expanded.
If it shows Disconnected and the command is right, the folder is not trusted. A
stdio server only starts in a trusted folder, so tell me to run `gemini trust`
here. This is the failure that looks like a broken install and is not one.
If it is configured but never connects, check the top-level `mcp` object for an
`allowed` list that does not name `refactron`.
You are looking for a server named `refactron` exposing exactly
ONE tool: `verify_change`.
If the server is connected but no tool appears, the handshake failed. Prove the
binary itself works by sending it one initialize request:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
A working server replies on one line with serverInfo.name "refactron". If that
works and the client still shows nothing, the fault is the config: check the
root key and check that the file parses.
STEP 6 - Prove it works with one real verification.
Do not skip this. A connected server is not a working server.
Pick one small source file that this project's test suite exercises. Propose a
real but behaviour-preserving edit to it: reorder the operands of a commutative
expression, rename a local variable, that kind of thing. One or two lines.
Do NOT write that edit to disk. Call verify_change with the proposal instead:
repoRoot the ABSOLUTE path to this repository
edits [{ "path": "",
"newContent": "" }]
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified rather than the installed
one. Use PYTHONPATH=src for a src layout.
Write the command in module form (`python3 -m pytest`), NOT as a
bare console script (`pytest`): a console script cannot be measured
on Windows or under pyenv, asdf and nix, and coverage then reports
that it could not be determined.
Verify the change BEFORE it exists on disk. The shadow tree is a copy of the
working tree, so if you write the change first and then pass a `git diff` of
it, the diff no longer applies and you get "diff did not apply (stale base?)"
back instead of a verdict.
Verification runs the whole test suite in a shadow copy, so it can take minutes
on a real project. That is the work, not a hang.
STEP 7 - Report, then stop.
Tell me:
- which file you wrote, or which command you ran
- the exact `verdict` and the exact `reason` from the response
- the value of `coverage.tool`: "coverage.py" means coverage was measured,
"none" means it was not
Apply nothing. The step 6 edit was a probe. Confirm with `git status` that the
working tree is exactly as dirty as you found it, and no more.
Do not describe a SAFE verdict as "correct", "proven", or "guaranteed". SAFE
means the project's own tests ran the changed code and stayed green. It
inherits exactly what those tests check, and a weak suite yields a weak SAFE.
```
Prefer to do it yourself? The rest of this page is the same setup by hand.
## Config location
| Scope | Path | Applies to |
| ------- | ---------------------------------------------- | ----------------- |
| User | `~/.gemini/settings.json` | Every project |
| Project | `.gemini/settings.json` in the repository root | This project only |
`gemini mcp add` defaults to **project** scope, so it writes `.gemini/settings.json` unless you ask otherwise.
## Add it
```bash theme={null}
gemini mcp add refactron refactron-mcp
```
That writes the project file. For every project on the machine, use user scope:
```bash theme={null}
gemini mcp add --scope user refactron refactron-mcp
```
By hand, add this to `settings.json` alongside the objects already there:
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "refactron-mcp",
"timeout": 900000
}
}
}
```
`timeout` is in **milliseconds** here, not seconds. Gemini CLI defaults to 600000 (10 minutes), which is the same order as Refactron's own 600 second test-gate default, so a suite that runs long enough to hit one will be near the other. Set it above your slowest full suite run.
To pin the version and skip the global install:
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"],
"timeout": 900000
}
}
}
```
The `-p` flag is required. `refactron-mcp` is a second binary of the `refactron` package, not a package of its own.
## Verify the connection
```bash theme={null}
gemini mcp list
```
```text theme={null}
✓ refactron: command: refactron-mcp (stdio) - Connected
```
Inside a session, the `/mcp` slash command shows connected servers with their tools expanded. You are looking for one tool, `verify_change`, under `refactron`.
## Troubleshooting
* **The server shows `Disconnected` and the command is right**: Gemini CLI only starts a stdio server in a trusted folder. Run `gemini trust` in the project directory, then list again. This is the failure that looks like a broken install and is not one.
* **`gemini mcp add` put it somewhere unexpected**: the default scope is project, so the entry landed in `.gemini/settings.json` in whatever directory you ran it from. Re-run with `--scope user` for a machine-wide entry.
* **`command not found` on launch**: run `which refactron-mcp`. If it prints nothing, run `npm install -g refactron`, or switch to the `npx` form above.
* **A verification is cut off partway**: `timeout` is milliseconds. `900` means 0.9 seconds, not 15 minutes, and every call fails instantly.
* **Confirmation prompts on every call**: set `"trust": true` on the `refactron` entry to skip them. The server reads your repository and writes only to a temporary shadow copy, so this is a reasonable server to trust. It is a per-server setting, so it does not loosen anything else.
* **The server is configured but excluded**: check the top-level `mcp` object for an `allowed` list. If `mcp.allowed` is set and does not name `refactron`, the CLI never connects to it.
# Any other client
Source: https://docs.refactron.dev/mcp/other-clients
Connect Refactron to any MCP client that can launch a stdio server, plus the root keys and config shapes each client family expects.
Refactron is an ordinary stdio MCP server. Any client that can launch a subprocess and speak JSON-RPC over its standard streams can run it.
## Set it up with your agent
One prompt, written for an MCP client that this documentation does not cover by name to read rather than you. It installs the
server, registers it, reloads, and proves the tool works with a real
verification.
```text theme={null}
Set up the Refactron MCP server for yourself in this repository and prove it
works before you tell me it is done. Do the steps in order.
You are running in an MCP client that this documentation does not cover by name.
STEP 1 - Check the prerequisites.
Run `node --version`. Refactron needs Node.js 18 or newer. If it is older or
missing, stop and tell me.
Run `python3 --version`, then check that `pytest` and `coverage` are
importable. Coverage attestation is Python-only, and it is what makes a
coverage-backed SAFE verdict possible. Without it the server still runs and
still gates the change, but every verdict caps at UNPROVEN.
STEP 2 - Install the server.
Run `which refactron-mcp`, or `where refactron-mcp` on Windows. If it prints a
path, go to step 3. Otherwise install it:
npm install -g refactron
That puts two binaries on PATH: `refactron` (the CLI) and `refactron-mcp` (the
MCP server). If you cannot install globally, install nothing and use the npx
form in step 3 instead.
Do not use `pip install refactron` for this. The PyPI wrapper provides the
`refactron` command only. It does not ship `refactron-mcp`.
STEP 3 - Register the server.
First work out which client you are running in, from your own runtime, not
from anything in this repository. If you genuinely cannot tell, ask me before
you write any file.
Refactron is an ordinary stdio MCP server: command `refactron-mcp`, no
arguments, no environment, no API key. Only the root key differs by client:
Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Cline
JSON, root key "mcpServers"
VS Code with Copilot JSON, root key "servers", plus "type": "stdio"
Zed JSON, top-level key "context_servers"
Codex CLI TOML, table [mcp_servers.refactron]
The server object, for every client that takes JSON:
{ "refactron": { "command": "refactron-mcp" } }
Without a global install, use this instead. The `-p` flag is required, because
`refactron-mcp` is a second binary of the `refactron` package and not a package
of its own:
{ "refactron": { "command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"] } }
Merge into any existing config rather than overwriting it.
Set a tool timeout if your client has one, and check the unit: Cline and Codex
CLI count seconds, Gemini CLI counts milliseconds. A verification runs the whole
test suite, so any default under a minute cuts it off and reports a failure
that is really a timeout.
STEP 4 - Reload.
Reload however your client requires: a new session, a full application restart,
a settings toggle, or a refresh button.
If you cannot trigger it yourself, say so plainly and tell me exactly what to
click. Do not claim the setup is done before the server is connected.
STEP 5 - Confirm the tool is exposed.
Use your client's own command or panel where one exists: `claude mcp list`,
`codex mcp list`, `gemini mcp list`, or the MCP panel in an editor.
You are looking for a server named `refactron` exposing exactly
ONE tool: `verify_change`.
If the server is connected but no tool appears, the handshake failed. Prove the
binary itself works by sending it one initialize request:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
A working server replies on one line with serverInfo.name "refactron". If that
works and the client still shows nothing, the fault is the config: check the
root key and check that the file parses.
STEP 6 - Prove it works with one real verification.
Do not skip this. A connected server is not a working server.
Pick one small source file that this project's test suite exercises. Propose a
real but behaviour-preserving edit to it: reorder the operands of a commutative
expression, rename a local variable, that kind of thing. One or two lines.
Do NOT write that edit to disk. Call verify_change with the proposal instead:
repoRoot the ABSOLUTE path to this repository
edits [{ "path": "",
"newContent": "" }]
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified rather than the installed
one. Use PYTHONPATH=src for a src layout.
Write the command in module form (`python3 -m pytest`), NOT as a
bare console script (`pytest`): a console script cannot be measured
on Windows or under pyenv, asdf and nix, and coverage then reports
that it could not be determined.
Verify the change BEFORE it exists on disk. The shadow tree is a copy of the
working tree, so if you write the change first and then pass a `git diff` of
it, the diff no longer applies and you get "diff did not apply (stale base?)"
back instead of a verdict.
Verification runs the whole test suite in a shadow copy, so it can take minutes
on a real project. That is the work, not a hang.
STEP 7 - Report, then stop.
Tell me:
- which file you wrote, or which command you ran
- the exact `verdict` and the exact `reason` from the response
- the value of `coverage.tool`: "coverage.py" means coverage was measured,
"none" means it was not
Apply nothing. The step 6 edit was a probe. Confirm with `git status` that the
working tree is exactly as dirty as you found it, and no more.
Do not describe a SAFE verdict as "correct", "proven", or "guaranteed". SAFE
means the project's own tests ran the changed code and stayed green. It
inherits exactly what those tests check, and a weak suite yields a weak SAFE.
```
Prefer to do it yourself? The rest of this page is the same setup by hand.
## What every client needs to know
| Setting | Value |
| ----------- | -------------------- |
| Transport | stdio |
| Command | `refactron-mcp` |
| Arguments | none |
| Environment | none required |
| Server name | `refactron` |
| Version | `0.3.0` |
| Tools | one, `verify_change` |
There is no HTTP or SSE endpoint, no API key, and no network call. The server reads your repository, runs your tests in a temporary shadow copy, and writes the verdict back over stdout.
## The root key differs by client
This is where most setups fail. The block is otherwise identical.
| Client family | Format | Root key |
| ---------------------------------------------------------------- | ------ | ----------------- |
| Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Cline | JSON | `mcpServers` |
| VS Code with GitHub Copilot | JSON | `servers` |
| Zed | JSON | `context_servers` |
| Codex CLI | TOML | `[mcp_servers.*]` |
The `mcpServers` form, which most clients accept:
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "refactron-mcp"
}
}
}
```
## Without a global install
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"]
}
}
}
```
The `-p` flag is required. `refactron-mcp` is a second binary of the `refactron` package, not a package of its own, so `npx refactron-mcp` looks up a package by that name and fails with a registry 404 unless a global install already put the binary on your `PATH`.
## Clients without a page of their own
### Zed
Zed calls MCP servers "context servers" and configures them in its main `settings.json`, at the top-level key `context_servers`. A block copied from Claude Desktop or Cursor does nothing here, with no error.
| OS | Path |
| ------------ | ----------------------------- |
| macOS, Linux | `~/.config/zed/settings.json` |
| Windows | `%APPDATA%\Zed\settings.json` |
```json theme={null}
{
"context_servers": {
"refactron": {
"command": "refactron-mcp",
"args": [],
"env": {}
}
}
}
```
Zed restarts the context server process when you save `settings.json`, so no editor restart is needed. Some builds also expect `"source": "custom"` on a hand-written entry. If the server does not appear after saving, add it through **Agent Panel** then **Settings** then **Add Custom Server**, which writes the shape your build expects.
### Cline
Cline manages servers from its own panel inside VS Code, backed by `cline_mcp_settings.json` in the extension's storage directory. Open it with the **MCP Servers** icon at the top of the Cline pane, then **Configure MCP Servers**.
| OS | Path |
| ------- | --------------------------------------------------------------------------------------------------------------- |
| macOS | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` |
| Linux | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "refactron-mcp",
"disabled": false,
"timeout": 900
}
}
}
```
`timeout` is in seconds here and it matters. Cline defaults to 60, and `verify_change` runs your whole test suite, so a real project blows past that and Cline reports a failure that is really a timeout. Cline stores this file separately from VS Code's own `.vscode/mcp.json`: configuring one does not configure the other.
## From a source checkout
Contributors running an unpublished build point the client at the compiled server with an absolute path:
```bash theme={null}
git clone https://github.com/Refactron-ai/refactron
cd refactron
npm install
npm run build
```
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "node",
"args": ["/absolute/path/to/refactron/dist/mcp/server.js"]
}
}
}
```
## Confirm it works before blaming the client
Send one `initialize` request straight to the binary:
```bash theme={null}
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
```
```json theme={null}
{
"result": {
"protocolVersion": "2024-11-05",
"capabilities": { "tools": { "listChanged": true } },
"serverInfo": { "name": "refactron", "version": "0.3.0" }
},
"jsonrpc": "2.0",
"id": 1
}
```
If that works and your client still shows nothing, the problem is the client config: check the root key, the JSON or TOML validity, and whether the client inherits the `PATH` that holds `refactron-mcp`.
## Client requirements that trip people up
* **A test-suite run is the unit of work.** Clients with a default tool timeout under a minute will cut off a real verification. Raise the timeout where the client allows it, and check the unit: Cline and Codex CLI count seconds, Gemini CLI counts milliseconds.
* **Absolute paths only.** `repoRoot` must be an absolute path. Clients that pass a relative working directory will not help you here.
* **Tools need an agent mode.** Chat-only or ask-only modes in most editors do not call tools at all.
# MCP server
Source: https://docs.refactron.dev/mcp/overview
Refactron over the Model Context Protocol: one tool, verify_change, that returns SAFE, UNSAFE, or UNPROVEN on a proposed change before an agent lands it.
Refactron ships an [MCP](https://modelcontextprotocol.io) server that exposes exactly one tool: **`verify_change`**. An agent hands it a repository root and a proposed change, and gets back a verdict backed by your real test suite, run in an isolated shadow tree.
The server speaks **stdio**, identifies itself as `refactron` version `0.3.0`, and runs entirely on your machine. It never writes to your repository: applying the change stays the agent's job, after a verdict the agent trusts.
The fastest way in is to let your agent do the setup. Every client page below opens with a copy-only prompt that installs the server, registers it, reloads the client, and gets a first real verdict, written for that client specifically.
Prefer to do it by hand? Pick your client below, or follow the [MCP quickstart](/mcp/quickstart).
```text theme={null}
From now on, in this repository, verify every code change with the Refactron
verify_change MCP tool BEFORE you write it to disk.
The loop:
1. Work out the change you want to make. Do not apply it yet.
2. Call verify_change with:
repoRoot the ABSOLUTE path to this repository
edits [{ path, newContent }] with the full proposed contents of each
file you want to change, OR unifiedDiff, a unified diff of the
change against the CURRENT working tree
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified. Use PYTHONPATH=src for a
src layout. Write the command in module form (`python3 -m
pytest`), NOT as a bare console script (`pytest`): a console
script cannot be measured on Windows or under pyenv, asdf and
nix, and coverage then reports that it could not be determined.
3. Read the `verdict` field and act on it.
SAFE Apply the change. Report the verdict and quote the `reason`. Also
say what SAFE does not cover: your suite ran the changed code and
stayed green, which is only as strong as its assertions. If
coverage.changedStatements shows a low covered/total ratio, say so
rather than presenting SAFE as full coverage.
UNSAFE Do NOT apply anything. A gate failed, which means your change broke
something. Read `reason` and the failing entry in `gates`, fix YOUR
change, and call verify_change again. Repeat until it is not UNSAFE.
Never work around this by weakening or deleting a test. If you touch
a test file, the report lists it in testFilesChanged and I will check.
UNPROVEN Do NOT apply yet. Read `reason` to find out which kind this is:
"the changed code is not exercised by any test" means the suite ran
and nothing executed your lines. Write the tests named in the
`missingTests` array, add them to the same verify_change call, and
re-verify. Aim to turn this into SAFE. If a missingTests hint says a
line is excluded from coverage (`# pragma: no cover`, `if
TYPE_CHECKING:`), do NOT try to write a test for it. No test can
reach it. Flag it for human review.
"coverage of the changed code could not be determined" means no
measurement happened at all. Coverage is Python-only today, so a
TypeScript, JavaScript, or mixed-language change always lands here
and no test you write moves it. The gates still passed. Report this
plainly and let me decide. Do not present it as SAFE.
"no test runner detected" or "baseline tests already fail" means
nothing could be proven either way. Stop and tell me.
4. Never describe a SAFE verdict as "verified correct", "proven correct", or
"guaranteed safe". It means the project's own tests ran the changed code and
stayed green. It inherits exactly what those tests check.
5. If the tool returns an error instead of a verdict, read the message. "no
edits provided" means you passed neither `edits` nor `unifiedDiff`. "diff did
not apply (stale base?)" means you already wrote the change to disk, so the
diff no longer applies to the tree being copied: pass `edits` instead, or
revert first. A message about deletions, renames, copies, or binary files
means the change uses an operation the tool refuses to verify, so tell me and
verify that part by hand.
```
### Make it stick across sessions
Writes that rule into the project, so every session and every teammate inherits it.
```text theme={null}
Add a Refactron verification rule to this project's agent rules file, so the
behavior persists across sessions.
Pick the right file for this repo, and create it if it is missing:
- AGENTS.md at the repo root, the cross-tool convention
- CLAUDE.md at the repo root, for Claude Code
- .cursor/rules/refactron.mdc, or .cursorrules on older Cursor, for Cursor
- .windsurfrules for Windsurf
- .github/copilot-instructions.md for GitHub Copilot
- GEMINI.md at the repo root, for Gemini CLI
Append this section verbatim. Do not remove anything already in the file.
## Verification (required)
Verify every code change with the Refactron `verify_change` MCP tool before
writing it to disk. Pass `repoRoot` as an absolute path and the change as
`edits` or `unifiedDiff`. Verify before the change exists on disk: the shadow
tree copies the working tree, so a diff of an already-written change will not
apply.
- `SAFE`: apply it, and report the verdict. `SAFE` means the project's tests ran
the changed code and stayed green. It is suite-approved, not proven correct:
every changed statement a test could reach was executed, but a green suite is
only as strong as its assertions.
- `UNSAFE`: do not apply. Fix the change and re-verify. Never weaken a test to
turn a verdict green.
- `UNPROVEN`: do not apply yet. If the reason names uncovered code, write the
tests listed in `missingTests` and re-verify. If the reason is that coverage
could not be determined, say so and ask a human. Coverage is Python-only, so a
non-Python change cannot reach `SAFE` today.
```
### Why the wording in these prompts matters
Every prompt tells the agent, more than once, not to report `SAFE` as "correct". That is deliberate.
`SAFE` means the gates passed and your suite exercised the changed code. It does not mean the change is right. A real example from Refactron's own hardening runs: changing `<=` to `<` in Jinja2's `truncate` filter genuinely changes behavior at the boundary, all 911 tests still pass, the changed line is covered, and the verdict is `SAFE`. The verdict is correct about what it claims and is still not a proof of correctness.
An agent that reports `SAFE` as "verified correct" has laundered a test-suite result into a guarantee. That is the one failure mode this tool exists to prevent, so the prompts spend words on it.
## Then use it
```text theme={null}
Set up the Refactron MCP server for yourself in this repository and prove it
works before you tell me it is done. Do the steps in order.
You are running in GitHub Copilot in VS Code.
STEP 1 - Check the prerequisites.
Run `node --version`. Refactron needs Node.js 18 or newer. If it is older or
missing, stop and tell me.
Run `python3 --version`, then check that `pytest` and `coverage` are
importable. Coverage attestation is Python-only, and it is what makes a
coverage-backed SAFE verdict possible. Without it the server still runs and
still gates the change, but every verdict caps at UNPROVEN.
STEP 2 - Install the server.
Run `which refactron-mcp`, or `where refactron-mcp` on Windows. If it prints a
path, go to step 3. Otherwise install it:
npm install -g refactron
That puts two binaries on PATH: `refactron` (the CLI) and `refactron-mcp` (the
MCP server). If you cannot install globally, install nothing and use the npx
form in step 3 instead.
Do not use `pip install refactron` for this. The PyPI wrapper provides the
`refactron` command only. It does not ship `refactron-mcp`.
STEP 3 - Register the server.
Create `.vscode/mcp.json` in the repository root.
The root key here is "servers", NOT "mcpServers", and each server needs
"type": "stdio". This is the mistake people make most often: a block copied
from Claude Desktop or Cursor loads nothing here, silently, with no error.
{ "servers": { "refactron": { "type": "stdio",
"command": "refactron-mcp" } } }
Without a global install, use this instead. The `-p` flag is required, because
`refactron-mcp` is a second binary of the `refactron` package and not a package
of its own:
{ "servers": { "refactron": { "type": "stdio", "command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"] } } }
If step 5 reports `spawn refactron-mcp ENOENT`, the binary is not on the PATH
VS Code inherited. Use the absolute path from `which refactron-mcp` as
"command".
STEP 4 - Reload.
Run "MCP: List Servers" from the Command Palette and start `refactron`.
If you cannot reach the Command Palette yourself, say so plainly and tell me
exactly what to click. Wait for me before you continue.
STEP 5 - Confirm the tool is exposed.
"MCP: List Servers" shows `refactron` with a Running status. Selecting it
offers Show Output and the start command.
In the Copilot Chat pane the mode selector must be on Agent, and then the tools
picker lists `verify_change` under `refactron`. Ask and Edit modes do not call
tools at all.
GitHub Copilot CLI keeps its own MCP config and expects "mcpServers".
Configuring VS Code does not configure the CLI.
You are looking for a server named `refactron` exposing exactly
ONE tool: `verify_change`.
If the server is connected but no tool appears, the handshake failed. Prove the
binary itself works by sending it one initialize request:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
A working server replies on one line with serverInfo.name "refactron". If that
works and the client still shows nothing, the fault is the config: check the
root key and check that the file parses.
STEP 6 - Prove it works with one real verification.
Do not skip this. A connected server is not a working server.
Pick one small source file that this project's test suite exercises. Propose a
real but behaviour-preserving edit to it: reorder the operands of a commutative
expression, rename a local variable, that kind of thing. One or two lines.
Do NOT write that edit to disk. Call verify_change with the proposal instead:
repoRoot the ABSOLUTE path to this repository
edits [{ "path": "",
"newContent": "" }]
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified rather than the installed
one. Use PYTHONPATH=src for a src layout.
Write the command in module form (`python3 -m pytest`), NOT as a
bare console script (`pytest`): a console script cannot be measured
on Windows or under pyenv, asdf and nix, and coverage then reports
that it could not be determined.
Verify the change BEFORE it exists on disk. The shadow tree is a copy of the
working tree, so if you write the change first and then pass a `git diff` of
it, the diff no longer applies and you get "diff did not apply (stale base?)"
back instead of a verdict.
Verification runs the whole test suite in a shadow copy, so it can take minutes
on a real project. That is the work, not a hang.
STEP 7 - Report, then stop.
Tell me:
- which file you wrote, or which command you ran
- the exact `verdict` and the exact `reason` from the response
- the value of `coverage.tool`: "coverage.py" means coverage was measured,
"none" means it was not
Apply nothing. The step 6 edit was a probe. Confirm with `git status` that the
working tree is exactly as dirty as you found it, and no more.
Do not describe a SAFE verdict as "correct", "proven", or "guaranteed". SAFE
means the project's own tests ran the changed code and stayed green. It
inherits exactly what those tests check, and a weak suite yields a weak SAFE.
```
Prefer to do it yourself? The rest of this page is the same setup by hand.
## The root key is `servers`, not `mcpServers`
Claude Desktop, Cursor, Windsurf, and Cline all use `mcpServers`. VS Code uses `servers`. A config copied from any of those clients loads nothing here, with no error: VS Code simply sees no servers.
## Config location
| Scope | Path | Applies to |
| --------- | ----------------------------------------- | ------------------- |
| Workspace | `.vscode/mcp.json` in the repository root | This workspace only |
| User | `mcp.json` in your VS Code profile folder | Every workspace |
Open the user file from the Command Palette with **MCP: Open User Configuration**. For the workspace file, create `.vscode/mcp.json` yourself.
## Add it
```json theme={null}
{
"servers": {
"refactron": {
"type": "stdio",
"command": "refactron-mcp"
}
}
}
```
To pin the version and skip the global install:
```json theme={null}
{
"servers": {
"refactron": {
"type": "stdio",
"command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"]
}
}
}
```
The `-p` flag is required. `refactron-mcp` is a second binary of the `refactron` package, not a package of its own.
## Verify the connection
Run **MCP: List Servers** from the Command Palette. `refactron` appears with a `Running` status; select it for **Show Output** and the start command.
In the Copilot Chat pane, switch the mode selector to **Agent**, then open the tools picker. `verify_change` is listed under `refactron` with a checkbox.
## Troubleshooting
* **No servers listed**: check the root key. It is `servers`. A copied `mcpServers` block is the usual cause.
* **The server sits at `Stopped`**: open **MCP: List Servers**, select `refactron`, then **Start Server**, and read **Show Output** for the launch error.
* **`spawn refactron-mcp ENOENT`**: the binary is not on the `PATH` VS Code inherited. Run `which refactron-mcp` in a terminal and use that absolute path as `command`, or use the `npx` form.
* **The tool never gets called**: Copilot only calls tools in **Agent** mode. Ask and Edit modes do not.
* **GitHub Copilot CLI does not read this file**: the CLI keeps its own MCP config and expects `mcpServers`. Configuring VS Code does not configure the CLI.
* **A verification takes minutes**: `verify_change` runs your real test suite in a shadow copy.
# Windsurf
Source: https://docs.refactron.dev/mcp/windsurf
Add the Refactron MCP server to Windsurf Cascade by editing ~/.codeium/windsurf/mcp_config.json.
Windsurf keeps MCP servers in a single file under your home directory, shared across every workspace. Cascade picks them up after a refresh.
## Set it up with your agent
One prompt, written for Windsurf to read rather than you. It installs the
server, registers it, reloads, and proves the tool works with a real
verification.
```text theme={null}
Set up the Refactron MCP server for yourself in this repository and prove it
works before you tell me it is done. Do the steps in order.
You are running in Windsurf.
STEP 1 - Check the prerequisites.
Run `node --version`. Refactron needs Node.js 18 or newer. If it is older or
missing, stop and tell me.
Run `python3 --version`, then check that `pytest` and `coverage` are
importable. Coverage attestation is Python-only, and it is what makes a
coverage-backed SAFE verdict possible. Without it the server still runs and
still gates the change, but every verdict caps at UNPROVEN.
STEP 2 - Install the server.
Run `which refactron-mcp`, or `where refactron-mcp` on Windows. If it prints a
path, go to step 3. Otherwise install it:
npm install -g refactron
That puts two binaries on PATH: `refactron` (the CLI) and `refactron-mcp` (the
MCP server). If you cannot install globally, install nothing and use the npx
form in step 3 instead.
Do not use `pip install refactron` for this. The PyPI wrapper provides the
`refactron` command only. It does not ship `refactron-mcp`.
STEP 3 - Register the server.
Edit `~/.codeium/windsurf/mcp_config.json`, or
%USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows, root key
"mcpServers". This one file is shared across every workspace.
{ "mcpServers": { "refactron": { "command": "refactron-mcp" } } }
Merge into the existing object if the file already has servers, and validate
the JSON. Windsurf drops the whole file when it cannot parse it, so one stray
comma removes every server I have.
Without a global install, use this instead. The `-p` flag is required, because
`refactron-mcp` is a second binary of the `refactron` package and not a package
of its own:
{ "mcpServers": { "refactron": { "command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"] } } }
STEP 4 - Reload.
Windsurf reads the config on refresh or restart, never on save.
You cannot do this yourself. Tell me to click Refresh in the Cascade MCP panel,
under the hammer icon, and wait for me before you continue.
STEP 5 - Confirm the tool is exposed.
Ask me to confirm that `refactron` is listed with a green dot under the hammer
icon in the Cascade panel, with one tool beneath it.
Windsurf caps how many tools it exposes to Cascade. Refactron adds exactly one,
but if I am near the cap, tell me which server to disable.
You are looking for a server named `refactron` exposing exactly
ONE tool: `verify_change`.
If the server is connected but no tool appears, the handshake failed. Prove the
binary itself works by sending it one initialize request:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' | refactron-mcp
A working server replies on one line with serverInfo.name "refactron". If that
works and the client still shows nothing, the fault is the config: check the
root key and check that the file parses.
STEP 6 - Prove it works with one real verification.
Do not skip this. A connected server is not a working server.
Pick one small source file that this project's test suite exercises. Propose a
real but behaviour-preserving edit to it: reorder the operands of a commutative
expression, rename a local variable, that kind of thing. One or two lines.
Do NOT write that edit to disk. Call verify_change with the proposal instead:
repoRoot the ABSOLUTE path to this repository
edits [{ "path": "",
"newContent": "" }]
testCmd the project's test command, if it is not obvious. For a Python
project installed into the environment (an editable
`pip install -e .` included), prefix it with PYTHONPATH=. so the
tests import the copy being verified rather than the installed
one. Use PYTHONPATH=src for a src layout.
Write the command in module form (`python3 -m pytest`), NOT as a
bare console script (`pytest`): a console script cannot be measured
on Windows or under pyenv, asdf and nix, and coverage then reports
that it could not be determined.
Verify the change BEFORE it exists on disk. The shadow tree is a copy of the
working tree, so if you write the change first and then pass a `git diff` of
it, the diff no longer applies and you get "diff did not apply (stale base?)"
back instead of a verdict.
Verification runs the whole test suite in a shadow copy, so it can take minutes
on a real project. That is the work, not a hang.
STEP 7 - Report, then stop.
Tell me:
- which file you wrote, or which command you ran
- the exact `verdict` and the exact `reason` from the response
- the value of `coverage.tool`: "coverage.py" means coverage was measured,
"none" means it was not
Apply nothing. The step 6 edit was a probe. Confirm with `git status` that the
working tree is exactly as dirty as you found it, and no more.
Do not describe a SAFE verdict as "correct", "proven", or "guaranteed". SAFE
means the project's own tests ran the changed code and stayed green. It
inherits exactly what those tests check, and a weak suite yields a weak SAFE.
```
Prefer to do it yourself? The rest of this page is the same setup by hand.
## Config location
| OS | Path |
| ------------ | ------------------------------------------------- |
| macOS, Linux | `~/.codeium/windsurf/mcp_config.json` |
| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
Windsurf can open it for you: in the Cascade panel, click the hammer icon, then **Configure**.
## Add it
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "refactron-mcp"
}
}
}
```
To pin the version and skip the global install:
```json theme={null}
{
"mcpServers": {
"refactron": {
"command": "npx",
"args": ["-y", "-p", "refactron", "refactron-mcp"]
}
}
}
```
The `-p` flag is required. `refactron-mcp` is a second binary of the `refactron` package, not a package of its own.
Save the file, then click **Refresh** in the Cascade MCP panel. Windsurf does not reload the file on save.
## Verify the connection
Click the hammer icon in the Cascade panel. `refactron` is listed with a green dot and one tool: `verify_change`.
Ask Cascade to confirm:
```text theme={null}
List the tools you have from the refactron MCP server.
```
## Troubleshooting
* **Nothing changes after editing the file**: press **Refresh** in the MCP panel. Windsurf reads the config on refresh or restart, never on save.
* **The server is listed but red**: the command did not launch. Run `which refactron-mcp`. If it prints nothing, run `npm install -g refactron`, or use the `npx` form above.
* **Invalid JSON**: Windsurf drops the whole file when it cannot parse it, so one stray comma removes every server. Validate before refreshing.
* **Tool call limits**: Windsurf caps the number of tools it exposes to Cascade. Refactron adds exactly one, but if you are near the cap, disable a server you are not using.
* **A verification takes minutes**: `verify_change` runs your real test suite in a shadow copy. That is the work, not a hang.
# Overview
Source: https://docs.refactron.dev/overview
Prove that any change, your AI agent's, a codemod's, or your own, preserves the behavior your tests check, or find out it can't be proven. Refactron runs your real tests in an isolated shadow tree and returns a reproducible SAFE, UNSAFE, or UNPROVEN verdict.
## What is Refactron?
Refactron is the **verification layer for AI code change**. As agents write more of your code, the bottleneck moves from *generating* changes to *trusting* them. Refactron is the deterministic gate that answers one question about any diff (your AI agent's, a codemod's, or your own):
> **Did this change preserve the behavior your tests check, and can you prove it?**
It applies the change in an isolated **shadow tree**, runs three gates against it (syntax, then imports, then your real test suite) and checks whether your tests actually exercise the lines that changed. It returns one of three verdicts. Your working tree is never touched.