> ## 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 Code > Register the Refactron MCP server with Claude Code using the claude mcp add command or a project .mcp.json. Claude Code has a built-in command for this, so you do not have to edit a file by hand. ## Set it up with your agent One prompt, written for Claude Code 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 Claude 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@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. Run: claude mcp add refactron -- refactron-mcp The `--` separator is required. Use `--scope project` instead if I asked for a config the whole team gets; that writes `.mcp.json` in the repository root. 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: claude mcp add refactron -- npx -y -p refactron@0.3.0 refactron-mcp STEP 4 - Reload. Claude Code picks the server up on the next session. If you are mid-session and it does not appear in step 5, tell me to restart `claude`. A project-scoped `.mcp.json` also needs a one-time approval. If step 5 shows "Pending approval", tell me to start `claude` in this directory and approve the server once. STEP 5 - Confirm the tool is exposed. Run: claude mcp list `refactron` should show as Connected. `claude mcp get refactron` prints the full record, including scope and resolved command. Inside a session, `/mcp` lists connected servers and their tools. 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": "", "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. 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 | Where it is written | Who sees it | | --------- | -------------------------------------------------------------- | -------------------------------- | | `local` | `~/.claude.json`, under the current project path (the default) | You, in this project only | | `user` | `~/.claude.json`, at the top level | You, in every project | | `project` | `.mcp.json` in the repository root | Everyone who checks out the repo | ## Add it ```bash theme={null} claude mcp add refactron -- refactron-mcp ``` ```text theme={null} Added stdio MCP server refactron with command: refactron-mcp to local config ``` To share the server with your team, commit it at project scope: ```bash theme={null} claude mcp add --scope project refactron -- refactron-mcp ``` That writes `.mcp.json` in the repository root: ```json theme={null} { "mcpServers": { "refactron": { "type": "stdio", "command": "refactron-mcp", "args": [], "env": {} } } } ``` To pin the version without a global install, register the `npx` form instead: ```bash theme={null} claude mcp add refactron -- npx -y -p refactron@0.3.0 refactron-mcp ``` ## Verify the connection ```bash theme={null} claude mcp list ``` ```text theme={null} refactron: refactron-mcp - ✔ Connected ``` For the full record, including scope and resolved command: ```bash theme={null} claude mcp get refactron ``` Inside a session, `/mcp` lists connected servers and their tools. You are looking for one tool, `verify_change`, under `refactron`. ## Troubleshooting * **`⏸ Pending approval (run 'claude' to approve)`**: a project-scoped `.mcp.json` needs your approval before it runs. Start `claude` in that directory and approve the server once. * **`✘ Failed to connect`**: the command is not on your `PATH`. Run `which refactron-mcp`. If it prints nothing, run `npm install -g refactron@0.3.0`, or re-register with the `npx` form above. * **The server connects but no tool appears**: the handshake failed. Send one `initialize` request straight to the binary as in the [MCP quickstart](/mcp/quickstart#2-smoke-test-the-server-without-a-client) to see whether the server or the client is at fault. * **Registered in the wrong project**: local scope is keyed to the directory you ran `claude mcp add` in. Run `claude mcp list` from the project you meant, and re-add there or use `--scope user`. * **Removing it**: `claude mcp remove refactron`, adding `-s project` or `-s user` if you did not use the default scope.