scripts(docs[mcp_swap]): clarify global-config + simple-detection scope

The script's previous docstring implied broad cross-CLI parity with
the actual CLIs' install/discovery surface. In practice it writes
only to the four canonical *global* config paths and probes binaries
via ``shutil.which`` + file-exists. Workspace configs
(``$PWD/.cursor/mcp.json``, ``$PWD/.gemini/settings.json``), npm
prefixes, Homebrew paths, and post-migration locations like
``~/.claude/local/claude`` are intentionally not handled — those
match each CLI's native installer logic, which this script does not
duplicate.

Add an explicit "Scope" section to the module docstring and an "Out
of scope" subsection to ``scripts/README.md`` so contributors know
where to use ``cursor mcp add`` / ``gemini mcp add`` directly. No
behaviour change.

Author: tony

scripts/README.md

@@ -59,7 +59,7 @@ invocation with no reinstall step.
 
 ### Scope
 
-Covers four CLIs and their canonical config paths:
+Covers four CLIs and their canonical **global** config paths:
 
 | CLI    | Config                       | Format |
 |--------|-------------------------------|--------|
@@ -72,6 +72,19 @@ 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.
 
+#### Out of scope (use the CLI's native command)
+
+- **Workspace / project-local configs** for Cursor and Gemini
+  (`$PWD/.cursor/mcp.json`, `$PWD/.gemini/settings.json`). When
+  workspace precedence matters, use `cursor mcp add` / `gemini mcp add`
+  directly — workspace files take precedence over the global ones this
+  script writes.
+- **Custom binary install locations.** Detection is `shutil.which` plus
+  the file existing at the configured global path. Homebrew, npm
+  prefixes (`~/.npm-global/bin`), and post-migration paths
+  (`~/.claude/local/claude`, `~/.gemini/local/gemini`) are picked up
+  only when the binary is already on `PATH`.
+
 ### Extending to a new CLI
 
 Add an entry to the `CLIS` table in `mcp_swap.py` and extend the three

scripts/mcp_swap.py

@@ -25,6 +25,29 @@
 $ uv run scripts/mcp_swap.py use-local
 $ uv run scripts/mcp_swap.py revert
 ```
+
+Scope
+-----
+This script is best-effort and intentionally narrow:
+
+- **Global configs only.** Writes to ``~/.cursor/mcp.json``,
+  ``~/.claude.json``, ``~/.codex/config.toml``, and
+  ``~/.gemini/settings.json``. Workspace / project-local configs
+  (``$PWD/.cursor/mcp.json``, ``$PWD/.gemini/settings.json``,
+  per-project ``projects.<abs>.mcpServers`` entries inside
+  ``~/.claude.json`` *are* recognised for Claude only) are NOT
+  walked — workspace files for Cursor/Gemini are silently ignored.
+  When workspace precedence matters, run the CLI's own
+  ``cursor mcp add ...`` / ``gemini mcp add ...`` directly.
+- **Simple binary detection.** Probing is ``shutil.which(<binary>)``
+  plus ``<config_path>.exists()``. Custom install locations
+  (Homebrew, npm prefixes, ``~/.npm-global/bin``,
+  ``~/.claude/local/claude``, ``~/.gemini/local/gemini``) are picked
+  up only if the binary is on ``PATH``. FastMCP's installer probes
+  these locations directly; this script does not.
+- **Single config shape per CLI.** No fallback paths, no merge of
+  multiple sources. If your setup deviates from the defaults above,
+  use the CLI's native ``mcp`` subcommand instead.
 """
 
 from __future__ import annotations