Claude Desktop

Claude Desktop reads one JSON file at launch. There is no CLI, and changes take effect only after a full restart.

Set it up with your agent

One prompt, written for Claude Desktop to read rather than you. It installs the server, registers it, reloads, and proves the tool works with a real verification.

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 Claude Desktop.

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@0.3.0

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.

Claude Desktop has no CLI. Edit its config file, root key "mcpServers":

    macOS   ~/Library/Application Support/Claude/claude_desktop_config.json
    Windows %APPDATA%\Claude\claude_desktop_config.json
    Linux   ~/.config/Claude/claude_desktop_config.json

Create the file if it is missing. If it already has servers, add "refactron" as
another key inside the existing "mcpServers" object rather than adding a second
"mcpServers" block:

    { "mcpServers": { "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:

    { "mcpServers": { "refactron": { "command": "npx",
        "args": ["-y", "-p", "refactron@0.3.0", "refactron-mcp"] } } }

Validate the JSON before you finish. Claude Desktop skips a malformed config
silently, so a trailing comma looks exactly like a broken install.

Claude Desktop launches from the desktop environment, not from your shell, so
it does not inherit PATH additions made in .zshrc or .bashrc. If step 5 reports
`spawn refactron-mcp ENOENT`, put the absolute path from `which refactron-mcp`
in "command" instead.

STEP 4 - Reload.

Claude Desktop reads that file once at launch, and it needs a FULL quit and
reopen. Closing the window is not enough on macOS.

You cannot do this yourself. Tell me to press Cmd+Q, or quit from the Claude
menu, and reopen the app. Wait for me before you continue.

STEP 5 - Confirm the tool is exposed.

Ask me to open Settings, then Developer, and read you the server list.
`refactron` should be listed with a `running` status. In a chat, the tools
control below the message box lists the connected servers.

If it failed to start, the logs are per-server: on macOS
~/Library/Logs/Claude/mcp-server-refactron.log, on Windows
%APPDATA%\Claude\logs\.

You are looking for a server named `refactron`, version 0.3.0, 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": "<repo-relative path>",
                 "newContent": "<the full proposed file contents>" }]
    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.

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	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

The app opens this file for you: Settings then Developer then Edit Config. If the file does not exist yet, create it with the contents below.

Add it

{
  "mcpServers": {
    "refactron": {
      "command": "refactron-mcp"
    }
  }
}

If you already have servers configured, add refactron as another key inside the existing mcpServers object rather than adding a second mcpServers block. To pin the version and skip the global install:

{
  "mcpServers": {
    "refactron": {
      "command": "npx",
      "args": ["-y", "-p", "refactron@0.3.0", "refactron-mcp"]
    }
  }
}

The -p flag is required. refactron-mcp is a second binary of the refactron package, not a package of its own. Quit Claude Desktop completely and reopen it. Closing the window is not enough on macOS: use Claude then Quit, or Cmd+Q.

Verify the connection

Open Settings then Developer. refactron appears in the server list with a running status. In a chat, the tools control below the message box lists the connected servers. Under refactron you should see exactly one tool: verify_change.

Troubleshooting

The server does not appear at all: the JSON is invalid. Claude Desktop skips a malformed config silently. Check it with node -e "JSON.parse(require('fs').readFileSync('<path>','utf8'))" and look for a trailing comma.
spawn refactron-mcp ENOENT in the logs: Claude Desktop launches from the desktop environment, not your shell, so it does not inherit PATH additions made in .zshrc or .bashrc. Use the absolute path from which refactron-mcp as the command value.
Reading the logs: macOS writes them to ~/Library/Logs/Claude/, one mcp-server-refactron.log per server. Windows uses %APPDATA%\Claude\logs\.
Edits appear to do nothing: the config is read once at launch. Quit the app fully and reopen.
A verification times out: verify_change runs your whole test suite, which can take minutes. That is the work, not a hang.

Get started

Connect your client

Reference

Set it up with your agent

Config location

Add it

Verify the connection

Troubleshooting

​Set it up with your agent

​Config location

​Add it

​Verify the connection

​Troubleshooting

Set it up with your agent

Config location

Add it

Verify the connection

Troubleshooting