> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refactron.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop

> Add the Refactron MCP server to Claude Desktop by editing claude_desktop_config.json, then restart the app.

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.

<div className="agent-prompt">
  ```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 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.
  ```
</div>

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.