> ## 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.

# Any other client

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

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

  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@0.3.0", "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`, 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.

## 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@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, 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_Lib_TS
cd Refactron_Lib_TS
npm install
npm run build
```

```json theme={null}
{
  "mcpServers": {
    "refactron": {
      "command": "node",
      "args": ["/absolute/path/to/Refactron_Lib_TS/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.