seam-code 0.3.0__py3-none-any.whl

seam/installer/__init__.py

@@ -0,0 +1,67 @@
+"""Agent-config installer for `seam install` / `seam uninstall`.
+
+Writes an MCP stdio server entry ("seam") into a coding agent's config so the
+agent auto-discovers the local Seam server. CLI-only — the MCP server itself is
+read-only, so there is no `seam_install` tool.
+
+Layering (leaf → composite):
+  jsonfile.py / tomlfile.py  — pure file format ops (stdlib json / tomlkit), no Seam deps
+  core.py                    — AgentTarget ABC, InstallResult, shared JSON install/uninstall
+  claude.py / cursor.py / codex.py — one AgentTarget each (own path + format)
+  this module                — TARGETS registry + helpers (get_target, resolve_seam_command)
+
+Adding an agent later = one target file + one registry entry.
+"""
+
+import shutil
+import sys
+from pathlib import Path
+
+from seam.installer.claude import ClaudeTarget
+from seam.installer.codex import CodexTarget
+from seam.installer.core import AgentTarget, InstallResult
+from seam.installer.cursor import CursorTarget
+
+# Registry — keys are the `--target` values the CLI accepts (besides "all").
+TARGETS: dict[str, AgentTarget] = {
+    "claude": ClaudeTarget(),
+    "cursor": CursorTarget(),
+    "codex": CodexTarget(),
+}
+
+
+def get_target(name: str) -> AgentTarget | None:
+    """Return the target for `name`, or None if unknown (CLI maps None → INVALID_INPUT)."""
+    return TARGETS.get(name)
+
+
+def resolve_seam_command() -> tuple[str, bool]:
+    """Resolve the absolute executable to put in the agent config.
+
+    Returns (command, found). The agent spawns the server with an unknown working
+    directory and PATH, so we want an ABSOLUTE, self-contained command. Resolution
+    order, most-to-least reliable:
+      1. sys.argv[0] — when invoked as the `seam` console script, this IS that
+         script's path (no PATH/cwd assumptions). Only trusted when it exists and is
+         named seam* (under pytest/`python -m` it is the test runner — skip it then).
+      2. shutil.which("seam") — the installed console script on PATH.
+      3. bare "seam" with found=False — correct once published / on PATH; CLI warns.
+    """
+    argv0 = sys.argv[0] if sys.argv else ""
+    if argv0:
+        candidate = Path(argv0)
+        if candidate.name.startswith("seam") and candidate.exists():
+            return str(candidate.resolve()), True
+    found = shutil.which("seam")
+    if found:
+        return found, True
+    return "seam", False
+
+
+__all__ = [
+    "TARGETS",
+    "AgentTarget",
+    "InstallResult",
+    "get_target",
+    "resolve_seam_command",
+]

seam/installer/claude.py

@@ -0,0 +1,97 @@
+"""Claude Code install target.
+
+Project scope → <root>/.mcp.json, key mcpServers.seam (auto-discovered, team-shareable).
+User scope    → ~/.claude.json, key projects.<abs-root>.mcpServers.seam (per-project local,
+                matching `claude mcp add --scope local`).
+Entry shape requires "type": "stdio" (Claude Code requires it; not implied by `command`).
+"""
+
+import json
+from pathlib import Path
+
+from seam.installer import guide
+from seam.installer.core import AgentTarget, InstallResult, install_entry, uninstall_entry
+from seam.installer.markdownfile import (
+    remove_block,
+    remove_file,
+    upsert_block,
+    wrap_block,
+    write_file,
+)
+
+_SERVER_NAME = "seam"
+
+
+class ClaudeTarget(AgentTarget):
+    name = "claude"
+
+    def supported_locations(self) -> list[str]:
+        return ["project", "user"]
+
+    def config_path(self, root: Path, location: str) -> Path:
+        if location == "project":
+            return root / ".mcp.json"
+        return Path.home() / ".claude.json"
+
+    def _key_path(self, root: Path, location: str) -> list[str]:
+        if location == "project":
+            return ["mcpServers", _SERVER_NAME]
+        # User scope nests servers per absolute project path.
+        return ["projects", str(root), "mcpServers", _SERVER_NAME]
+
+    def _entry(self, command: str, args: list[str]) -> dict[str, object]:
+        return {"type": "stdio", "command": command, "args": args}
+
+    def install(self, root: Path, location: str, command: str, args: list[str]) -> InstallResult:
+        return install_entry(
+            self.config_path(root, location),
+            self._key_path(root, location),
+            self._entry(command, args),
+        )
+
+    def uninstall(self, root: Path, location: str) -> InstallResult:
+        return uninstall_entry(self.config_path(root, location), self._key_path(root, location))
+
+    def render_entry(self, command: str, args: list[str]) -> str:
+        return json.dumps({"mcpServers": {_SERVER_NAME: self._entry(command, args)}}, indent=2)
+
+    # ── CLI guidance: a project skill + a thin CLAUDE.md discovery pointer ─────
+
+    def _skill_path(self, root: Path) -> Path:
+        return root / ".claude" / "skills" / _SERVER_NAME / "SKILL.md"
+
+    def _claude_md(self, root: Path) -> Path:
+        return root / "CLAUDE.md"
+
+    def install_guidance(self, root: Path) -> list[InstallResult]:
+        skill = self._skill_path(root)
+        claude_md = self._claude_md(root)
+        return [
+            InstallResult(write_file(skill, guide.render_skill()), str(skill)),
+            InstallResult(
+                upsert_block(claude_md, guide.render_claude_hook(), marker=guide.BLOCK_MARKER),
+                str(claude_md),
+            ),
+        ]
+
+    def uninstall_guidance(self, root: Path) -> list[InstallResult]:
+        skill = self._skill_path(root)
+        claude_md = self._claude_md(root)
+        action = remove_file(skill)
+        # Tidy the now-empty skill directory we created; ignore if non-empty/missing.
+        skill_dir = skill.parent
+        if skill_dir.exists() and not any(skill_dir.iterdir()):
+            skill_dir.rmdir()
+        return [
+            InstallResult(action, str(skill)),
+            InstallResult(remove_block(claude_md, marker=guide.BLOCK_MARKER), str(claude_md)),
+        ]
+
+    def guidance_previews(self, root: Path) -> list[tuple[str, str]]:
+        return [
+            (str(self._skill_path(root)), guide.render_skill()),
+            (
+                str(self._claude_md(root)),
+                wrap_block(guide.render_claude_hook(), guide.BLOCK_MARKER),
+            ),
+        ]

seam/installer/codex.py

@@ -0,0 +1,94 @@
+"""Codex install target.
+
+User scope → ~/.codex/config.toml, table [mcp_servers.seam] with command + args.
+Codex's project-scoped .codex/config.toml only applies in "trusted projects", so
+the MVP supports user scope only. Uses tomlkit (tomlfile) to preserve the user's
+existing comments/formatting on round-trip.
+"""
+
+from pathlib import Path
+
+import tomlkit
+
+from seam.installer import guide
+from seam.installer.core import AgentTarget, InstallResult
+from seam.installer.markdownfile import remove_block, upsert_block, wrap_block
+from seam.installer.tomlfile import (
+    atomic_write_toml,
+    delete_server_table,
+    get_server_table,
+    load_toml,
+    set_server_table,
+)
+
+_SERVER_NAME = "seam"
+
+
+class CodexTarget(AgentTarget):
+    name = "codex"
+
+    def supported_locations(self) -> list[str]:
+        return ["user"]
+
+    def config_path(self, root: Path, location: str) -> Path:
+        return Path.home() / ".codex" / "config.toml"
+
+    def _entry(self, command: str, args: list[str]) -> dict[str, object]:
+        return {"command": command, "args": args}
+
+    def install(self, root: Path, location: str, command: str, args: list[str]) -> InstallResult:
+        path = self.config_path(root, location)
+        existed = path.exists()
+        backed_up = _backup_if_corrupt(path)
+        entry = self._entry(command, args)
+
+        doc = load_toml(path) or tomlkit.document()
+        if get_server_table(doc, _SERVER_NAME) == entry:
+            return InstallResult("unchanged", str(path), entry, backed_up)
+
+        set_server_table(doc, _SERVER_NAME, entry)
+        atomic_write_toml(path, doc)
+        return InstallResult("created" if not existed else "updated", str(path), entry, backed_up)
+
+    def uninstall(self, root: Path, location: str) -> InstallResult:
+        path = self.config_path(root, location)
+        doc = load_toml(path)
+        if doc is None:
+            return InstallResult("not_present", str(path))
+        if delete_server_table(doc, _SERVER_NAME):
+            atomic_write_toml(path, doc)
+            return InstallResult("removed", str(path))
+        return InstallResult("not_present", str(path))
+
+    def render_entry(self, command: str, args: list[str]) -> str:
+        doc = tomlkit.document()
+        set_server_table(doc, _SERVER_NAME, self._entry(command, args))
+        return tomlkit.dumps(doc).strip()
+
+    # ── CLI guidance: an inline AGENTS.md block (Codex has no skill/rule) ──────
+    # Project-scoped (repo root), unlike Codex's user-only MCP config.
+
+    def _agents_md(self, root: Path) -> Path:
+        return root / "AGENTS.md"
+
+    def install_guidance(self, root: Path) -> list[InstallResult]:
+        agents = self._agents_md(root)
+        action = upsert_block(agents, guide.render_codex_block(), marker=guide.BLOCK_MARKER)
+        return [InstallResult(action, str(agents))]
+
+    def uninstall_guidance(self, root: Path) -> list[InstallResult]:
+        agents = self._agents_md(root)
+        return [InstallResult(remove_block(agents, marker=guide.BLOCK_MARKER), str(agents))]
+
+    def guidance_previews(self, root: Path) -> list[tuple[str, str]]:
+        agents = self._agents_md(root)
+        return [(str(agents), wrap_block(guide.render_codex_block(), guide.BLOCK_MARKER))]
+
+
+def _backup_if_corrupt(path: Path) -> bool:
+    """Back up a present-but-unparseable config.toml before we overwrite it."""
+    if path.exists() and load_toml(path) is None:
+        backup = path.with_suffix(path.suffix + ".backup")
+        backup.write_bytes(path.read_bytes())
+        return True
+    return False

seam/installer/core.py

@@ -0,0 +1,127 @@
+"""Installer core — the AgentTarget contract, InstallResult, and the shared
+idempotent JSON merge used by the JSON-format targets (Claude, Cursor).
+
+The TOML target (Codex) shares InstallResult but implements its own merge in
+codex.py via tomlfile — TOML table editing differs enough from nested-dict JSON
+that forcing it through this path would be more convoluted than separate code.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from seam.installer.jsonfile import (
+    atomic_write_json,
+    delete_in,
+    get_in,
+    load_json,
+    set_in,
+)
+
+
+@dataclass
+class InstallResult:
+    """Outcome of a single install/uninstall against one target+location.
+
+    action:
+      created      — config file did not exist; we created it with the entry
+      updated      — config file existed; we added or changed our entry
+      unchanged    — our entry already deep-equals the desired entry (no write)
+      removed      — uninstall deleted an existing entry
+      not_present  — uninstall found nothing to remove
+    backed_up: a present-but-corrupt config was copied to <path>.backup before write.
+    """
+
+    action: str
+    path: str
+    entry: dict[str, Any] | None = None
+    backed_up: bool = False
+
+
+class AgentTarget(ABC):
+    """A coding agent Seam can install itself into. One concrete class per agent."""
+
+    name: str
+
+    @abstractmethod
+    def supported_locations(self) -> list[str]:
+        """Which `--location` values this target accepts (e.g. ["project", "user"])."""
+
+    @abstractmethod
+    def config_path(self, root: Path, location: str) -> Path:
+        """Absolute path of the config file this target writes for `location`."""
+
+    @abstractmethod
+    def install(self, root: Path, location: str, command: str, args: list[str]) -> InstallResult:
+        """Write/merge the seam MCP entry. Idempotent."""
+
+    @abstractmethod
+    def uninstall(self, root: Path, location: str) -> InstallResult:
+        """Remove the seam MCP entry if present."""
+
+    @abstractmethod
+    def render_entry(self, command: str, args: list[str]) -> str:
+        """Human-readable preview of the entry this target would write (for --print-config)."""
+
+    # ── CLI-first guidance (the install default) ──────────────────────────────
+    # Guidance is the token-lean playbook the agent reads to use the `seam` CLI.
+    # It is ALWAYS project-scoped (it lives in the repo: a skill, a rule, or an
+    # AGENTS.md block), independent of the MCP `location` — so it ignores location
+    # and a target whose MCP is user-only (Codex) can still receive repo guidance.
+    # A target may write more than one artifact (Claude writes a skill + a hook),
+    # hence list[InstallResult].
+
+    @abstractmethod
+    def install_guidance(self, root: Path) -> list[InstallResult]:
+        """Write this target's CLI guidance artifact(s) into the repo. Idempotent."""
+
+    @abstractmethod
+    def uninstall_guidance(self, root: Path) -> list[InstallResult]:
+        """Remove this target's CLI guidance artifact(s) if present."""
+
+    @abstractmethod
+    def guidance_previews(self, root: Path) -> list[tuple[str, str]]:
+        """(path, content) pairs this target would write — for --print-config."""
+
+
+def _backup_if_corrupt(path: Path) -> bool:
+    """If `path` exists but does not parse as JSON, copy it to <path>.backup.
+
+    Protects a user's hand-edited config from being silently destroyed when we
+    have to overwrite an unparseable file. Returns True iff a backup was made.
+    """
+    if path.exists() and load_json(path) is None:
+        backup = path.with_suffix(path.suffix + ".backup")
+        backup.write_bytes(path.read_bytes())
+        return True
+    return False
+
+
+def install_entry(path: Path, key_path: list[str], entry: dict[str, Any]) -> InstallResult:
+    """Idempotently set `entry` at `key_path` in the JSON file at `path`.
+
+    Preserves every other key in the file. Deep-equal entry → unchanged (no write).
+    """
+    existed = path.exists()
+    backed_up = _backup_if_corrupt(path)
+    data = load_json(path) or {}
+
+    if get_in(data, key_path) == entry:
+        return InstallResult("unchanged", str(path), entry, backed_up)
+
+    set_in(data, key_path, entry)
+    atomic_write_json(path, data)
+    return InstallResult("created" if not existed else "updated", str(path), entry, backed_up)
+
+
+def uninstall_entry(path: Path, key_path: list[str]) -> InstallResult:
+    """Remove the leaf at `key_path` from the JSON file at `path`, if present."""
+    data = load_json(path)
+    if data is None:
+        # Absent or unparseable → nothing we recognize to remove.
+        return InstallResult("not_present", str(path))
+    if delete_in(data, key_path):
+        atomic_write_json(path, data)
+        return InstallResult("removed", str(path))
+    return InstallResult("not_present", str(path))

seam/installer/cursor.py

@@ -0,0 +1,61 @@
+"""Cursor install target.
+
+Project scope → <root>/.cursor/mcp.json; user/global scope → ~/.cursor/mcp.json.
+Both use {"mcpServers": {"seam": {"command", "args"}}}. Unlike Claude, Cursor does
+NOT use a "type" field — a command-based entry is stdio by definition.
+"""
+
+import json
+from pathlib import Path
+
+from seam.installer import guide
+from seam.installer.core import AgentTarget, InstallResult, install_entry, uninstall_entry
+from seam.installer.markdownfile import remove_file, write_file
+
+_SERVER_NAME = "seam"
+
+
+class CursorTarget(AgentTarget):
+    name = "cursor"
+
+    def supported_locations(self) -> list[str]:
+        return ["project", "user"]
+
+    def config_path(self, root: Path, location: str) -> Path:
+        if location == "project":
+            return root / ".cursor" / "mcp.json"
+        return Path.home() / ".cursor" / "mcp.json"
+
+    def _key_path(self) -> list[str]:
+        return ["mcpServers", _SERVER_NAME]
+
+    def _entry(self, command: str, args: list[str]) -> dict[str, object]:
+        return {"command": command, "args": args}
+
+    def install(self, root: Path, location: str, command: str, args: list[str]) -> InstallResult:
+        return install_entry(
+            self.config_path(root, location), self._key_path(), self._entry(command, args)
+        )
+
+    def uninstall(self, root: Path, location: str) -> InstallResult:
+        return uninstall_entry(self.config_path(root, location), self._key_path())
+
+    def render_entry(self, command: str, args: list[str]) -> str:
+        return json.dumps({"mcpServers": {_SERVER_NAME: self._entry(command, args)}}, indent=2)
+
+    # ── CLI guidance: an "Agent Requested" project rule (progressive) ─────────
+
+    def _rule_path(self, root: Path) -> Path:
+        # Must be `.mdc` (a plain `.md` in .cursor/rules/ is ignored by Cursor).
+        return root / ".cursor" / "rules" / f"{_SERVER_NAME}.mdc"
+
+    def install_guidance(self, root: Path) -> list[InstallResult]:
+        rule = self._rule_path(root)
+        return [InstallResult(write_file(rule, guide.render_cursor_rule()), str(rule))]
+
+    def uninstall_guidance(self, root: Path) -> list[InstallResult]:
+        rule = self._rule_path(root)
+        return [InstallResult(remove_file(rule), str(rule))]
+
+    def guidance_previews(self, root: Path) -> list[tuple[str, str]]:
+        return [(str(self._rule_path(root)), guide.render_cursor_rule())]

seam/installer/guide.py

@@ -0,0 +1,110 @@
+"""LEAF: the single source of Seam's agent-facing CLI guidance + per-format renderers.
+
+One guide body, rendered into each agent's cheapest native mechanism so the
+formats can never drift:
+
+  * Claude Code  → a project skill (`SKILL.md`): the description sits in the
+    always-loaded skill listing; the body loads only when the skill is invoked.
+  * Cursor       → an "Agent Requested" rule (`.mdc`): surfaced by its
+    `description`, pulled in only when relevant (`alwaysApply: false`).
+  * Codex        → an inline `AGENTS.md` block (Codex has no progressive
+    mechanism, so the full guide is always-loaded there).
+
+The thin CLAUDE.md hook is a separate, tiny always-loaded pointer that boosts
+skill-discovery reliability (~70-85% → ~95%) for ~20 tokens.
+
+Pure: string constants + string builders. No IO, no Seam deps, never raises.
+"""
+
+# Marker name for the shared-file blocks (AGENTS.md / CLAUDE.md). The
+# markdownfile leaf turns this into `<!-- seam:start -->` … `<!-- seam:end -->`.
+BLOCK_MARKER = "seam"
+
+# Retrieval-tuned discovery hook. No apostrophes and no "colon-space" so it is a
+# safe single-quoted YAML scalar in both the skill and the Cursor rule frontmatter.
+_DESCRIPTION = (
+    "Query the Seam code-intelligence index for this repo via the `seam` CLI "
+    "instead of grep — find callers, blast radius, symbol definitions, and repo "
+    "structure. Use when exploring or editing code in this repository."
+)
+_WHEN_TO_USE = (
+    'Use for "who calls X", "what breaks if I change X", "where is X defined", '
+    'or "map this repo".'
+)
+
+# The escalation ladder is the whole point: start cheap (--quiet names), escalate
+# to --json --lean only for risk tiers, full --json only for provenance.
+_GUIDE_BODY = """\
+# Using Seam (code intelligence)
+
+Seam has indexed this repo into `.seam/seam.db` — a symbol + call graph.
+Query it instead of grepping: faster, and far cheaper in tokens.
+
+## Keep the index fresh first
+- No `.seam/seam.db`?        → `seam init`
+- `seam status` says stale?  → `seam sync`
+
+## Escalation ladder — spend the fewest tokens, escalate only when needed
+1. Discover / orient   `seam search <text> --quiet` · `seam query <concept> --quiet`
+                       `seam context <symbol> --quiet`        (names + locations only)
+2. Change risk         `seam impact <symbol> --json --lean`   (risk tiers, no enrichment)
+3. Full provenance     `seam impact <symbol> --json`          (confidence, resolved_by)
+
+## When to reach for what
+- Unfamiliar area        → `seam query "<concept>" --quiet`
+- Before editing X       → `seam impact X --json --lean`   (d=1 = WILL_BREAK)
+- Trace how A reaches B  → `seam trace A B`
+- Before committing      → `seam changes`
+- Map repo / entrypoints → `seam structure --quiet` · `seam flows`
+
+Prefer Seam over grep/read for: "who calls X", "what breaks if I change X",
+"where is X defined", "what's in this area".
+
+## MCP alternative
+Same answers as native MCP tools if you prefer tool-calling: `seam install --with-mcp`.
+The CLI is the default because it costs fewer tokens."""
+
+# Thin always-loaded pointer for CLAUDE.md (Claude does not read AGENTS.md).
+_CLAUDE_HOOK = """\
+## Seam — this repo is indexed for code intelligence
+For structural questions (callers, blast radius, definitions, repo map) use the `seam`
+CLI instead of grep — start with `seam <cmd> --quiet`. Full usage: the `seam` skill.
+If `.seam/seam.db` is missing run `seam init`; if `seam status` is stale run `seam sync`."""
+
+
+def render_skill() -> str:
+    """Full `.claude/skills/seam/SKILL.md` — YAML frontmatter + the guide body."""
+    return (
+        "---\n"
+        "name: seam\n"
+        f"description: '{_DESCRIPTION}'\n"
+        f"when_to_use: '{_WHEN_TO_USE}'\n"
+        "---\n\n"
+        f"{_GUIDE_BODY}\n"
+    )
+
+
+def render_cursor_rule() -> str:
+    """Full `.cursor/rules/seam.mdc` — "Agent Requested" frontmatter + the guide body.
+
+    `alwaysApply: false` + a `description` + empty `globs` is the doc-confirmed
+    recipe for a description-surfaced (progressive) Cursor rule.
+    """
+    return (
+        "---\n"
+        f"description: '{_DESCRIPTION}'\n"
+        "globs:\n"
+        "alwaysApply: false\n"
+        "---\n\n"
+        f"{_GUIDE_BODY}\n"
+    )
+
+
+def render_codex_block() -> str:
+    """Block content for Codex `AGENTS.md` — the full guide (no progressive option)."""
+    return _GUIDE_BODY
+
+
+def render_claude_hook() -> str:
+    """Block content for the thin `CLAUDE.md` discovery pointer."""
+    return _CLAUDE_HOOK

seam/installer/jsonfile.py

@@ -0,0 +1,85 @@
+"""LEAF: pure JSON config-file operations for the installer (stdlib only).
+
+Used by the JSON-format targets (Claude `.mcp.json`, Cursor `.cursor/mcp.json`).
+No Seam dependencies, so targets compose these without import cycles. Every
+write is atomic (temp + os.replace) because a half-written agent config is
+silently skipped at the agent's startup — a crash mid-write must never corrupt it.
+"""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def load_json(path: Path) -> dict[str, Any] | None:
+    """Parse the JSON object at `path`, or None if absent OR unparseable.
+
+    None is intentionally ambiguous between "absent" and "corrupt" — the caller
+    disambiguates with `path.exists()` so it can back up a corrupt file before
+    overwriting it (see core._backup_if_corrupt).
+    """
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+        return None
+    # A top-level non-object (list/scalar) is not a config we can merge into.
+    return data if isinstance(data, dict) else None
+
+
+def atomic_write_json(path: Path, data: dict[str, Any]) -> None:
+    """Write `data` as pretty JSON to `path` atomically; create parent dirs."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2)
+            handle.write("\n")
+        os.replace(tmp, path)
+    except BaseException:
+        # Never leave the temp file behind on failure (disk-full, signal, etc.).
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def get_in(data: dict[str, Any], key_path: list[str]) -> Any:
+    """Return the value at the nested `key_path`, or None if any segment is missing."""
+    cur: Any = data
+    for key in key_path:
+        if not isinstance(cur, dict) or key not in cur:
+            return None
+        cur = cur[key]
+    return cur
+
+
+def set_in(data: dict[str, Any], key_path: list[str], value: Any) -> None:
+    """Set `value` at the nested `key_path`, creating intermediate dicts as needed.
+
+    A non-dict found at an intermediate segment is replaced with a dict — the
+    target key paths (mcpServers / projects.<root>.mcpServers) own their subtree.
+    """
+    cur = data
+    for key in key_path[:-1]:
+        nxt = cur.get(key)
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cur[key] = nxt
+        cur = nxt
+    cur[key_path[-1]] = value
+
+
+def delete_in(data: dict[str, Any], key_path: list[str]) -> bool:
+    """Delete the leaf at `key_path`. Return True iff something was removed."""
+    cur = data
+    for key in key_path[:-1]:
+        nxt = cur.get(key)
+        if not isinstance(nxt, dict):
+            return False
+        cur = nxt
+    if key_path[-1] in cur:
+        del cur[key_path[-1]]
+        return True
+    return False