scripts(feat[mcp_swap]): add cross-CLI MCP config detect/swap/revert tool

why: when developing an MCP server locally, each agent CLI (Claude, Codex,
Cursor, Gemini) needs its config pointed at the checkout so uv run picks
up source edits editable-style. Doing that by hand across four config
formats (three JSON shapes + TOML) is fragile — Codex's TOML in particular
needs comment/order preservation that sed/jq can't offer. A scripted swap
with timestamped backups + a state file makes the flow reversible and
reproducible across any MCP repo, not just this one.

what:
- Add scripts/mcp_swap.py as a PEP 723 single-file script modeled on
  ~/scripts/py/agentex_mcp.py: inline uv deps (tomlkit>=0.13),
  CLIName = Literal["claude","codex","cursor","gemini"], per-CLI
  get/set/delete on the MCP server entry. Subcommands: detect, status,
  use-local, revert. Server name + entry command auto-derived from the
  repo's pyproject.toml (libtmux-mcp -> libtmux, first [project.scripts]
  key for the entry).
- Claude's per-project keying (projects."<abs-repo>".mcpServers) is
  handled explicitly — only the current repo's key is rewritten, leaving
  other projects untouched. Claude's full entry shape is preserved
  (type/env fields).
- Codex TOML edits go through tomlkit so [notice] blocks, top-level
  comments, and sibling tables survive the round-trip. When no
  libtmux entry exists yet (common for Codex), use-local records
  action="added" so revert correctly removes the block.
- Safety: atomic tempfile+os.replace writes, timestamped
  .bak.mcp-swap-<ts> backups (never overwrites existing .bak.*), post-
  write re-parse validation with rollback on failure, --dry-run that
  prints unified diffs and writes nothing, state file at
  ~/.local/state/libtmux-mcp/mcp_swap.json tracking per-CLI backup paths.
- Add scripts/README.md with usage + extension notes (add an entry to
  CLIS and extend the three per-CLI branches).
- Add 12 tests in tests/test_mcp_swap.py using importlib.util to load
  the out-of-tree script: JSON round-trip (cursor/gemini), Claude
  per-project keying, Codex comment preservation + add-then-revert,
  unrelated-server preservation, --dry-run writes nothing,
  second-swap-is-noop, state-file cleared on full revert, spec helpers.
- Add four [group: 'mcp'] recipes to justfile: mcp-detect, mcp-status,
  mcp-use-local, mcp-revert.
- Add tomlkit>=0.13 to the dev dependency group so pytest can import
  the PEP 723 script without uv run bootstrapping.

Author: tony

justfile

@@ -119,6 +119,26 @@ watch-mypy:
 format-markdown:
     prettier --parser=markdown -w *.md docs/*.md docs/**/*.md CHANGES
 
+# Detect which CLI agents (claude/codex/cursor/gemini) exist on this machine
+[group: 'mcp']
+mcp-detect:
+    uv run scripts/mcp_swap.py detect
+
+# Show how each detected CLI resolves this MCP server today
+[group: 'mcp']
+mcp-status *args:
+    uv run scripts/mcp_swap.py status {{ args }}
+
+# Rewrite each detected CLI's config to run this checkout (editable)
+[group: 'mcp']
+mcp-use-local *args:
+    uv run scripts/mcp_swap.py use-local {{ args }}
+
+# Restore each CLI's config from the backup written by mcp-use-local
+[group: 'mcp']
+mcp-revert *args:
+    uv run scripts/mcp_swap.py revert {{ args }}
+
 [private]
 _entr-warn:
     @echo "----------------------------------------------------------"

pyproject.toml

@@ -70,6 +70,8 @@ dev = [
   "pytest-watcher",
   "pytest-xdist",
   "syrupy>=5.1.0",
+  # scripts/mcp_swap.py (PEP 723 script; dep listed here so tests can import it)
+  "tomlkit>=0.13",
   # Coverage
   "codecov",
   "coverage",

scripts/README.md

@@ -0,0 +1,80 @@
+# scripts/
+
+Developer utilities shipped with the repo but not part of the installed
+package.
+
+## `mcp_swap.py`
+
+Swap the libtmux MCP server entry across every detected agent CLI
+(Claude Code, Codex, Cursor, Gemini) so all four run the **local checkout**
+instead of a pinned PyPI release. Useful when testing a branch or working
+on the server itself.
+
+### Usage
+
+From the repo root:
+
+```console
+$ uv run scripts/mcp_swap.py detect      # which CLIs are installed?
+$ uv run scripts/mcp_swap.py status      # what does each point at today?
+$ uv run scripts/mcp_swap.py use-local --dry-run
+$ uv run scripts/mcp_swap.py use-local   # rewrite configs (with backups)
+$ uv run scripts/mcp_swap.py revert      # restore from backups
+```
+
+Or via `just`:
+
+```console
+$ just mcp-detect
+$ just mcp-status
+$ just mcp-use-local --dry-run
+$ just mcp-use-local
+$ just mcp-revert
+```
+
+### What `use-local` does
+
+For each detected CLI, the libtmux entry (or equivalent — derived from
+`pyproject.toml` project name, trailing `-mcp` stripped) is rewritten to:
+
+```
+command = "uv"
+args    = ["--directory", "<repo-abs-path>", "run", "libtmux-mcp"]
+```
+
+This matches Claude's conventional dev form and takes advantage of `uv
+run`'s automatic editable install — source edits flow through on the next
+invocation with no reinstall step.
+
+### Safety
+
+- Every rewrite writes a timestamped backup (`<config>.bak.mcp-swap-<ts>`)
+  before touching the file.
+- State is tracked in `~/.local/state/libtmux-mcp/mcp_swap.json` so
+  `revert` knows which backup to restore per CLI, including the "added"
+  case where Codex had no libtmux block before.
+- Writes are atomic (tempfile + `os.replace`) and re-validated by
+  re-parsing; a bad write is rolled back immediately.
+- `--dry-run` prints a unified diff and writes nothing.
+
+### Scope
+
+Covers four CLIs and their canonical config paths:
+
+| CLI    | Config                       | Format |
+|--------|-------------------------------|--------|
+| Claude | `~/.claude.json`              | JSON (per-project keying) |
+| Codex  | `~/.codex/config.toml`        | TOML (format-preserving via `tomlkit`) |
+| Cursor | `~/.cursor/mcp.json`          | JSON |
+| Gemini | `~/.gemini/settings.json`     | JSON |
+
+Claude's config is keyed per-project under the repo's absolute path — the
+script writes only under the current repo's key, leaving other projects'
+entries untouched.
+
+### Extending to a new CLI
+
+Add an entry to the `CLIS` table in `mcp_swap.py` and extend the three
+per-CLI branches in `get_server` / `set_server` / `delete_server`. Tests
+in `tests/test_mcp_swap.py` use a `fake_home` fixture that monkeypatches
+`CLIS`, so the extension pattern is already established.