> ## 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. # VS Code > Add the Refactron MCP server to VS Code with GitHub Copilot. Note the root key: VS Code uses servers, not mcpServers. VS Code reads MCP servers for GitHub Copilot's agent mode. Its config shape differs from every other client on one point, and it is the mistake people make most often. ## Set it up with your agent One prompt, written for GitHub Copilot in VS 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 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@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. 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@0.3.0", "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`, 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. ## 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@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. ## 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.