autodebug 0.5.1__py3-none-any.whl

autodebug/hub.py

@@ -0,0 +1,267 @@
+"""The AutoDebug service: one process per user that owns the debug session (docs/design.md, "The service").
+
+Every agent reaches the same session through it: the MCP server (`autodebug serve`, started by
+Cursor, VS Code or Visual Studio) and the command line (`autodebug run <tool> ...`), which any agent
+with a terminal can use when its app does not show the MCP tools. The session and the report's
+timeline live here, so they survive an MCP server being restarted or dropped by the IDE.
+
+Protocol: one JSON object per line over TCP on 127.0.0.1, every request carrying the token from
+`hub.json` in the state folder (readable only by this user). The first client that finds no service
+starts one in the background; it exits after IDLE_SECONDS without calls while no session is open.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+import os
+import secrets
+import socket
+import socketserver
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+from autodebug import __version__
+from autodebug.connection import state_folder
+from autodebug.tools import Debugger
+
+_LOG = logging.getLogger("autodebug")
+IDLE_SECONDS = 30 * 60
+MAX_LINE = 1024 * 1024
+CALL_TIMEOUT = 180  # longer than any tool's own wait (55 s) plus the IDE's answer
+_FINISHED = ("ended", "denied", "build_failed", "none")
+
+
+class ServiceError(Exception):
+    """The service could not be reached or started; the message says why and what to do."""
+
+
+def hub_file() -> Path:
+    return state_folder() / "hub.json"
+
+
+_CODE: list[str] = []
+
+
+def code_id() -> str:
+    """A fingerprint of this AutoDebug's Python code, so a service left running from before an update
+    (`git pull`, same version number) is replaced instead of answering with the old code."""
+    if not _CODE:
+        digest = hashlib.sha256()
+        for path in sorted(Path(__file__).resolve().parent.glob("*.py")):
+            digest.update(path.name.encode() + b"\0" + path.read_bytes().replace(b"\r\n", b"\n"))
+        _CODE.append(digest.hexdigest()[:16])
+    return _CODE[0]
+
+
+# -- the service ---------------------------------------------------------------------------
+
+
+class Hub:
+    def __init__(self, debugger: Debugger | None = None, idle_seconds: float = IDLE_SECONDS,
+                 info_file: Path | None = None) -> None:
+        self.debugger = debugger or Debugger()
+        self.idle_seconds = idle_seconds
+        self.info_file = info_file or hub_file()
+        self.token = secrets.token_hex(24)
+        self.code = code_id()
+        self.last_call = time.monotonic()
+        self._tool_lock = threading.Lock()  # one debugger action at a time, whoever asks
+        hub = self
+
+        class Handler(socketserver.StreamRequestHandler):
+            def handle(self) -> None:
+                line = self.rfile.readline(MAX_LINE + 1)
+                if not line or len(line) > MAX_LINE:
+                    return
+                reply = hub.answer(line)
+                try:
+                    self.wfile.write(json.dumps(reply, ensure_ascii=False).encode("utf-8") + b"\n")
+                except OSError:
+                    pass
+
+        class TCP(socketserver.ThreadingTCPServer):
+            daemon_threads = True
+            allow_reuse_address = False
+
+        self.server = TCP(("127.0.0.1", 0), Handler)
+        self.port = self.server.server_address[1]
+
+    def busy(self) -> bool:
+        """Whether a debug session is open, so the service must not exit or be replaced."""
+        status = (self.debugger._last_status or ("none",))[0]
+        return self.debugger.connection is not None and status not in _FINISHED
+
+    def answer(self, line: bytes) -> dict:
+        try:
+            request = json.loads(line)
+        except ValueError:
+            return {"error": "BAD_REQUEST", "message": "not JSON"}
+        if not isinstance(request, dict) or not hmac.compare_digest(str(request.get("token", "")), self.token):
+            return {"error": "BAD_TOKEN", "message": "wrong token"}
+        op = request.get("op")
+        if op == "ping":
+            return {"ok": True, "version": __version__, "code": self.code, "busy": self.busy(), "pid": os.getpid()}
+        if op == "shutdown":
+            if self.busy() and not request.get("force"):
+                return {"ok": False, "busy": True}
+            threading.Thread(target=self.server.shutdown, daemon=True).start()
+            return {"ok": True}
+        if op != "call":
+            return {"error": "BAD_REQUEST", "message": f"unknown op {op}"}
+        from autodebug.mcp_server import TOOLS, _valid, call_tool
+
+        name, arguments = request.get("name"), request.get("arguments") or {}
+        if name not in TOOLS:
+            return {"result": {"error": "BAD_REQUEST", "message": f"unknown tool {name}"}, "is_error": True}
+        if not _valid(arguments, TOOLS[name][1]):
+            return {"result": {"error": "BAD_REQUEST", "message": f"invalid arguments for {name}"}, "is_error": True}
+        self.last_call = time.monotonic()
+        with self._tool_lock:
+            result, is_error = call_tool(self.debugger, name, arguments)
+        self.last_call = time.monotonic()
+        return {"result": result, "is_error": is_error}
+
+    def _write_info(self) -> None:
+        self.info_file.parent.mkdir(parents=True, exist_ok=True)
+        info = {"port": self.port, "token": self.token, "pid": os.getpid(), "version": __version__, "code": self.code}
+        temporary = self.info_file.with_name(f"hub-{os.getpid()}.tmp")
+        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(info, handle)
+        os.replace(temporary, self.info_file)
+
+    def _remove_info(self) -> None:
+        try:
+            if json.loads(self.info_file.read_text(encoding="utf-8")).get("pid") == os.getpid():
+                self.info_file.unlink()
+        except (OSError, ValueError):
+            pass
+
+    def _watch_idle(self) -> None:
+        while True:
+            time.sleep(min(30.0, max(0.05, self.idle_seconds / 4)))
+            if time.monotonic() - self.last_call > self.idle_seconds and not self.busy():
+                _LOG.info("idle; the AutoDebug service exits")
+                self.server.shutdown()
+                return
+
+    def serve(self) -> None:
+        self._write_info()
+        threading.Thread(target=self._watch_idle, daemon=True).start()
+        try:
+            self.server.serve_forever(poll_interval=0.2)
+        finally:
+            self._remove_info()
+            self.server.server_close()
+            self.debugger.close()
+
+
+# -- clients ---------------------------------------------------------------------------------
+
+
+def _read_info() -> dict | None:
+    try:
+        info = json.loads(hub_file().read_text(encoding="utf-8"))
+        return info if isinstance(info.get("port"), int) and isinstance(info.get("token"), str) else None
+    except (OSError, ValueError):
+        return None
+
+
+def _request(info: dict, request: dict, timeout: float) -> dict:
+    with socket.create_connection(("127.0.0.1", info["port"]), timeout=timeout) as sock:
+        sock.settimeout(timeout)
+        sock.sendall(json.dumps({**request, "token": info["token"]}).encode("utf-8") + b"\n")
+        data = b""
+        while not data.endswith(b"\n"):
+            chunk = sock.recv(65536)
+            if not chunk:
+                break
+            data += chunk
+            if len(data) > 64 * MAX_LINE:
+                raise OSError("reply too long")
+    if not data:
+        raise OSError("the service closed the connection")
+    return json.loads(data)
+
+
+def _ping(info: dict | None) -> dict | None:
+    if not info:
+        return None
+    try:
+        reply = _request(info, {"op": "ping"}, 3)
+    except (OSError, ValueError):
+        return None
+    return reply if reply.get("ok") else None
+
+
+def _start_process() -> None:
+    """Start `autodebug hub` in the background, detached from the caller (an IDE may kill its MCP servers)."""
+    package_parent = str(Path(__file__).resolve().parent.parent)
+    env = dict(os.environ)
+    env["PYTHONPATH"] = os.pathsep.join(p for p in (package_parent, env.get("PYTHONPATH")) if p)
+    folder = state_folder()
+    folder.mkdir(parents=True, exist_ok=True)
+    log = open(folder / "hub.log", "ab")  # noqa: SIM115 — handed to the child
+    options: dict = {"stdin": subprocess.DEVNULL, "stdout": log, "stderr": log, "env": env, "close_fds": True}
+    command = [sys.executable, "-m", "autodebug", "hub"]
+    try:
+        if os.name == "nt":
+            flags = 0x08000000 | 0x00000200  # CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP
+            try:
+                subprocess.Popen(command, creationflags=flags | 0x01000000, **options)  # CREATE_BREAKAWAY_FROM_JOB
+            except OSError:
+                subprocess.Popen(command, creationflags=flags, **options)
+        else:
+            subprocess.Popen(command, start_new_session=True, **options)
+    finally:
+        log.close()
+
+
+def connect_service(start: bool = True, wait_seconds: float = 15) -> dict:
+    """The running service's connection info, starting it (or replacing an idle older version) if needed."""
+    info = _read_info()
+    alive = _ping(info)
+    if alive and (alive.get("version"), alive.get("code")) != (__version__, code_id()) and not alive.get("busy"):
+        try:
+            _request(info, {"op": "shutdown"}, 3)
+        except (OSError, ValueError):
+            pass
+        deadline = time.monotonic() + 5
+        while time.monotonic() < deadline and _ping(info):
+            time.sleep(0.1)
+        alive = None
+    if alive:
+        return info
+    if not start:
+        raise ServiceError("the AutoDebug service is not running")
+    _start_process()
+    deadline = time.monotonic() + wait_seconds
+    while time.monotonic() < deadline:
+        info = _read_info()
+        if _ping(info):
+            return info
+        time.sleep(0.1)
+    raise ServiceError(f"the AutoDebug service did not start; see {state_folder() / 'hub.log'}")
+
+
+def call(name: str, arguments: dict, timeout: float = CALL_TIMEOUT) -> tuple[dict, bool]:
+    """Run one tool in the shared service: (result, is_error). Raises ServiceError if it cannot be reached."""
+    info = connect_service()
+    try:
+        reply = _request(info, {"op": "call", "name": name, "arguments": arguments}, timeout)
+    except (OSError, ValueError) as exc:
+        raise ServiceError(f"lost the AutoDebug service during {name}: {exc}") from exc
+    if "result" not in reply:
+        raise ServiceError(f"the AutoDebug service refused the call: {reply.get('message') or reply}")
+    return reply["result"], bool(reply.get("is_error"))
+
+
+def status() -> dict | None:
+    """{version, busy, pid} of the running service, or None."""
+    return _ping(_read_info())

autodebug/install.py

@@ -0,0 +1,346 @@
+"""`autodebug setup`: package and install the extension, write the MCP entry."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import urllib.request
+import zipfile
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+EXTENSION_DIR = Path(__file__).with_name("extension")
+_FILES = (("package.json", "package.json"), ("extension.js", "extension.js"),
+          ("relay.js", "relay.js"), ("mcp.js", "mcp.js"), ("README.md", "readme.md"))
+#: Earlier extension IDs to remove so two versions never run side by side (the publisher was `autodebug`
+#: before the store publisher `SwagatTeejoram`).
+OLD_EXTENSIONS = ("autodebug.autodebug-bridge", "autodebug.autodebug")
+SERVER_NAME = "autodebug"
+#: MIT, as in the repository's LICENSE (kept here too: an installed package has no repository files).
+LICENSE_TEXT = """MIT License
+
+Copyright (c) 2026 TEEJORAM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+#: Where CI publishes the Visual Studio extension package for each version.
+VS_RELEASE = "https://github.com/TEEJORAM/AutoDebug/releases/download/visualstudio-v{version}/AutoDebug.VisualStudio.vsix"
+
+
+def manifest() -> dict:
+    return json.loads((EXTENSION_DIR / "package.json").read_text(encoding="utf-8"))
+
+
+def extension_id() -> str:
+    data = manifest()
+    return f"{data['publisher']}.{data['name']}"
+
+
+def build_vsix(folder: Path) -> Path:
+    """Write the extension as a .vsix (the layout `vsce` produces) and return its path."""
+    data = manifest()
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / f"{extension_id()}-{data['version']}.vsix"
+    attr = lambda v: escape(str(v), {'"': """})  # noqa: E731
+    vsixmanifest = f"""<?xml version="1.0" encoding="utf-8"?>
+<PackageManifest Version="2.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011" xmlns:d="http://schemas.microsoft.com/developer/vsx-schema-design/2011">
+  <Metadata>
+    <Identity Language="en-US" Id="{attr(data['name'])}" Version="{attr(data['version'])}" Publisher="{attr(data['publisher'])}" />
+    <DisplayName>{escape(data['displayName'])}</DisplayName>
+    <Description xml:space="preserve">{escape(data['description'])}</Description>
+    <Tags></Tags>
+    <Categories>{escape(','.join(data.get('categories', [])))}</Categories>
+    <GalleryFlags>Public</GalleryFlags>
+    <Properties>
+      <Property Id="Microsoft.VisualStudio.Code.Engine" Value="{attr(data['engines']['vscode'])}" />
+      <Property Id="Microsoft.VisualStudio.Code.ExtensionDependencies" Value="" />
+      <Property Id="Microsoft.VisualStudio.Code.ExtensionPack" Value="" />
+      <Property Id="Microsoft.VisualStudio.Code.ExtensionKind" Value="{attr(','.join(data.get('extensionKind', ['workspace'])))}" />
+      <Property Id="Microsoft.VisualStudio.Code.LocalizedLanguages" Value="" />
+      <Property Id="Microsoft.VisualStudio.Code.ExecutesCode" Value="true" />
+    </Properties>
+  </Metadata>
+  <Installation><InstallationTarget Id="Microsoft.VisualStudio.Code"/></Installation>
+  <Dependencies/>
+  <Assets>
+    <Asset Type="Microsoft.VisualStudio.Code.Manifest" Path="extension/package.json" Addressable="true" />
+    <Asset Type="Microsoft.VisualStudio.Services.Content.Details" Path="extension/readme.md" Addressable="true" />
+    <Asset Type="Microsoft.VisualStudio.Services.Content.License" Path="extension/LICENSE.txt" Addressable="true" />
+  </Assets>
+</PackageManifest>
+"""
+    content_types = ('<?xml version="1.0" encoding="utf-8"?>\n'
+                     '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+                     '<Default Extension=".json" ContentType="application/json"/>'
+                     '<Default Extension=".vsixmanifest" ContentType="text/xml"/>'
+                     '<Default Extension=".js" ContentType="application/javascript"/>'
+                     '<Default Extension=".md" ContentType="text/markdown"/></Types>')
+    entries = [("extension.vsixmanifest", vsixmanifest.encode()), ("[Content_Types].xml", content_types.encode())]
+    entries += [(f"extension/{target}", (EXTENSION_DIR / source).read_bytes()) for source, target in _FILES]
+    entries.append(("extension/LICENSE.txt", LICENSE_TEXT.encode()))
+    temporary = path.with_name(path.name + ".tmp")
+    with zipfile.ZipFile(temporary, "w", zipfile.ZIP_DEFLATED) as archive:
+        for name, payload in entries:
+            info = zipfile.ZipInfo(name, date_time=(2026, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_DEFLATED
+            archive.writestr(info, payload)
+    temporary.replace(path)
+    return path
+
+
+def ide_command(ide: str) -> str | None:
+    """The IDE's command-line launcher: PATH first, then the default install places."""
+    name = {"cursor": "cursor", "vscode": "code"}[ide]
+    found = shutil.which(name)
+    if found:
+        return found
+    local = Path(os.environ.get("LOCALAPPDATA", ""))
+    candidates = {
+        "cursor": [local / "Programs" / "cursor" / "resources" / "app" / "bin" / "cursor.cmd",
+                   Path("/Applications/Cursor.app/Contents/Resources/app/bin/cursor")],
+        "vscode": [local / "Programs" / "Microsoft VS Code" / "bin" / "code.cmd",
+                   Path(os.environ.get("ProgramFiles", "C:/Program Files")) / "Microsoft VS Code" / "bin" / "code.cmd",
+                   Path("/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code")],
+    }[ide]
+    return next((str(p) for p in candidates if str(p) not in (".", "") and p.is_file()), None)
+
+
+def install_extension(command: str, vsix: Path) -> subprocess.CompletedProcess:
+    for old in OLD_EXTENSIONS:
+        subprocess.run([command, "--uninstall-extension", old], capture_output=True, text=True, timeout=120, check=False)
+    return subprocess.run([command, "--install-extension", str(vsix), "--force"], capture_output=True, text=True,
+                          timeout=300, check=False)
+
+
+# -- Visual Studio ----------------------------------------------------------------
+
+
+def vsix_installer() -> str | None:
+    """Visual Studio's own VSIXInstaller.exe, found with vswhere (installed with every VS 2017+)."""
+    vswhere = Path(os.environ.get("ProgramFiles(x86)", "C:/Program Files (x86)")) / "Microsoft Visual Studio" / "Installer" / "vswhere.exe"
+    if not vswhere.is_file():
+        return None
+    result = subprocess.run([str(vswhere), "-latest", "-prerelease", "-version", "[17.0,19.0)", "-property", "installationPath"],
+                            capture_output=True, text=True, timeout=60, check=False)
+    folder = result.stdout.strip().splitlines()[-1] if result.stdout.strip() else ""
+    installer = Path(folder) / "Common7" / "IDE" / "VSIXInstaller.exe"
+    return str(installer) if folder and installer.is_file() else None
+
+
+def download_vs_extension(version: str, folder: Path) -> Path:
+    """Download the Visual Studio extension package CI built for this version."""
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / f"AutoDebug.VisualStudio-{version}.vsix"
+    temporary = path.with_name(path.name + ".tmp")
+    with urllib.request.urlopen(VS_RELEASE.format(version=version), timeout=120) as response:  # noqa: S310 (fixed https URL)
+        temporary.write_bytes(response.read())
+    if not zipfile.is_zipfile(temporary):
+        temporary.unlink()
+        raise ValueError("the downloaded Visual Studio extension is not a .vsix package")
+    temporary.replace(path)
+    return path
+
+
+#: VSIXInstaller's exit code when Visual Studio (or one of its helper processes) is still running.
+VSIX_BLOCKED = 2004
+
+
+def visual_studio_running() -> bool:
+    """Whether a Visual Studio window (devenv.exe) is open; the extension cannot be installed then."""
+    if sys.platform != "win32":
+        return False
+    result = subprocess.run(["tasklist", "/FI", "IMAGENAME eq devenv.exe", "/NH", "/FO", "CSV"],
+                            capture_output=True, text=True, timeout=30, check=False)
+    return "devenv.exe" in result.stdout.lower()
+
+
+VS_EXTENSION_ID = "AutoDebug.VisualStudio.4f9b2c71"  # Identity Id in visualstudio/Extension/source.extension.vsixmanifest
+
+
+def install_vs_extension(installer: str, vsix: Path) -> subprocess.CompletedProcess:
+    """Remove any installed copy first: VSIXInstaller refuses a package whose version is already installed,
+    so a fixed build of the same version would otherwise never replace the old one."""
+    subprocess.run([installer, "/quiet", f"/uninstall:{VS_EXTENSION_ID}"], capture_output=True, text=True,
+                   timeout=600, check=False)
+    return subprocess.run([installer, "/quiet", str(vsix)], capture_output=True, text=True, timeout=600, check=False)
+
+
+# -- instructions for agents ----------------------------------------------------------
+
+AGENTS_START = "<!-- autodebug:start -->"
+AGENTS_END = "<!-- autodebug:end -->"
+
+
+def agent_instructions(command: str) -> str:
+    return f"""{AGENTS_START}
+## Debugging with AutoDebug
+
+This project can be debugged with the IDE's own debugger (VS Code, Cursor or Visual Studio) through AutoDebug.
+
+- Use the `autodebug` MCP tools if they are in your tool list.
+- If they are not (some apps drop MCP tools), run the same tools in the terminal. It is the same session:
+  - `{command} run list_targets ide=visualstudio` (or `ide=cursor`, `ide=vscode`; omit when one IDE is open)
+  - `{command} run help` lists every tool and its arguments. Values need no JSON:
+    `breakpoints=geometry.cpp:16` `variables=total,i`; quote a whole pair that has spaces:
+    `"launch_configuration=geometry (Debug|x64)"`.
+- Do not read AutoDebug's source, connection files or IDE logs to find the tools: use the commands above.
+- `start_session` opens an Approve dialog in the IDE. Tell the developer to click **Approve** there
+  (it closes after 2 minutes). Nothing runs before that; a chat message is not an approval.
+- Order: `list_targets` → `start_session` (launch configuration, breakpoints, goal, and `build_task` from
+  `list_targets` so the program is built from the current source) → `wait` while it is
+  awaiting_approval, building or starting → `inspect`, `step`, `trace` → `stop_session` → `write_report`.
+  Call the tools one at a time. Paths are relative to the workspace folder that `list_targets` shows.
+{AGENTS_END}
+"""
+
+
+def write_agent_instructions(folder: str, command: str) -> Path:
+    """Add or refresh the AutoDebug section of <folder>/AGENTS.md (read by Cursor, Copilot, Codex and others)."""
+    path = Path(folder).expanduser().resolve() / "AGENTS.md"
+    block = agent_instructions(command)
+    text = path.read_text(encoding="utf-8") if path.is_file() else ""
+    if AGENTS_START in text and AGENTS_END in text:
+        before, rest = text.split(AGENTS_START, 1)
+        after = rest.split(AGENTS_END, 1)[1].lstrip("\n")
+        text = before + block + (("\n" + after) if after else "")
+    else:
+        text = (text.rstrip("\n") + "\n\n" if text.strip() else "") + block
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def has_agent_instructions(folder: str) -> bool:
+    path = Path(folder).expanduser().resolve() / "AGENTS.md"
+    return path.is_file() and AGENTS_START in path.read_text(encoding="utf-8", errors="replace")
+
+
+# -- MCP configuration ------------------------------------------------------------
+
+
+def server_entry(ide: str) -> dict:
+    """How the IDE starts this server: this Python, with `src` on the path when run from a checkout."""
+    entry: dict = {"type": "stdio", "command": sys.executable, "args": ["-m", "autodebug", "serve"]}
+    package = Path(__file__).resolve().parent
+    if (package.parent.name == "src") and (package.parents[1] / "pyproject.toml").is_file():
+        entry["env"] = {"PYTHONPATH": str(package.parent)}
+    return entry
+
+
+def claude_present() -> bool:
+    """Claude Code is installed: its command, or the files it keeps in the home folder."""
+    return bool(shutil.which("claude")) or (Path.home() / ".claude.json").is_file() or (Path.home() / ".claude").is_dir()
+
+
+def server_file() -> Path:
+    from autodebug.connection import state_folder
+
+    return state_folder() / "server.json"
+
+
+def write_server_file() -> Path:
+    """How to start the MCP server, for the extension to register it with VS Code or Cursor itself."""
+    entry = server_entry("any")
+    data = {"command": entry["command"], "args": entry["args"], "env": entry.get("env", {}),
+            "version": manifest()["version"]}
+    path = server_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + ".tmp")
+    temporary.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+    return path
+
+
+def config_file(ide: str, folder: str | None = None) -> Path:
+    if ide == "claude":  # Claude Code: user scope in ~/.claude.json, project scope in <folder>/.mcp.json
+        return (Path(folder).expanduser().resolve() / ".mcp.json") if folder else Path.home() / ".claude.json"
+    if ide == "visualstudio":  # Visual Studio's agent mode: <solution>/.mcp.json or %USERPROFILE%\.mcp.json
+        return (Path(folder).expanduser().resolve() if folder else Path.home()) / ".mcp.json"
+    if folder:
+        return Path(folder).expanduser().resolve() / (".cursor" if ide == "cursor" else ".vscode") / "mcp.json"
+    if ide == "cursor":
+        return Path.home() / ".cursor" / "mcp.json"
+    if sys.platform == "win32":
+        return Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming") / "Code" / "User" / "mcp.json"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Code" / "User" / "mcp.json"
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "Code" / "User" / "mcp.json"
+
+
+def _top_key(ide: str) -> str:
+    return "mcpServers" if ide in ("cursor", "claude") else "servers"
+
+
+def read_config(path: Path) -> dict:
+    """Read an MCP config, tolerating a BOM or UTF-16 (Windows PowerShell)."""
+    if not path.exists():
+        return {}
+    raw = path.read_bytes()
+    text = raw.decode("utf-16") if raw[:2] in (b"\xff\xfe", b"\xfe\xff") else raw.decode("utf-8-sig")
+    if not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
+    except ValueError as exc:
+        raise ValueError(f"{path} is not plain JSON (it may contain comments); add the entry by hand") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} does not contain a JSON object")
+    return data
+
+
+def write_config(ide: str, folder: str | None = None) -> Path:
+    """Add or replace the `autodebug` entry, keeping every other server."""
+    path = config_file(ide, folder)
+    data = read_config(path)
+    servers = data.setdefault(_top_key(ide), {})
+    if not isinstance(servers, dict):
+        raise ValueError(f"{path}: {_top_key(ide)} is not an object")
+    servers[SERVER_NAME] = server_entry(ide)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + ".tmp")
+    temporary.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+    return path
+
+
+def remove_config(ide: str, folder: str | None = None) -> Path | None:
+    """Remove the `autodebug` entry, keeping every other server; returns the file when one was removed."""
+    path = config_file(ide, folder)
+    try:
+        data = read_config(path)
+    except ValueError:
+        return None  # a file with comments is left for the developer
+    servers = data.get(_top_key(ide))
+    if not isinstance(servers, dict) or SERVER_NAME not in servers:
+        return None
+    del servers[SERVER_NAME]
+    temporary = path.with_name(path.name + ".tmp")
+    temporary.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+    return path
+
+
+def configured_entry(ide: str, folder: str | None = None) -> dict | None:
+    try:
+        entry = read_config(config_file(ide, folder)).get(_top_key(ide), {}).get(SERVER_NAME)
+    except (OSError, ValueError, AttributeError):
+        return None
+    return entry if isinstance(entry, dict) else None