Point opencode and pi at a local checkout or a PR

[tony]

scripts/mcp_swap.py points installed agent CLIs at a local checkout or a pull request. This extends it from six CLIs to eight and moves per-CLI behavior out of scattered branches onto the registry. Development tooling only — nothing under src/ changes.

Summary

• Add opencode — $XDG_CONFIG_HOME/opencode/opencode.jsonc, resolved the way opencode's own loader resolves it. It is the first config here that is neither plain JSON nor TOML, the first whose server map hangs off something other than mcpServers/mcp_servers, and the first whose entry packs argv into a single command array.
• Add pi — ~/.pi/agent/mcp.json. pi ships no MCP client of its own: its README says "No MCP" outright, and the released build contains no MCP code. That file is read by the third-party pi-mcp-adapter extension, so detect reports the missing prerequisite rather than presenting a swap that cannot take effect.
• Add a JSONC reader and writer that preserves comments. Values come from stdlib json after comments and trailing commas are blanked in place; writes are applied as text splices, so bytes outside a replaced value survive — including a comment written directly above the command it explains. No new dependency: the script's PEP 723 header still lists only tomlkit.
• Replace the four cli in (...) membership tuples in get_server / set_server / delete_server / _all_server_specs with two declarative CLIInfo fields. Two of those dispatches ended in a bare else that fell through to the TOML key, so a CLI present in CLIS but absent from one tuple reported "no entry" instead of failing; the other two raised AssertionError, which the caller did not catch.
• Add an opencode panel to the docs install picker. pi gets no panel — it ships no MCP client, so there is nothing for a reader to install into.

Behavior changes for the six existing CLIs

The refactor is not purely internal. Three things change for CLIs this PR does not otherwise touch:

• A container key holding something other than a table now raises RuntimeError naming the path. Only Claude had that guard before; Codex, Cursor, Gemini, Grok and agy would raise TypeError/AttributeError from setdefault — outside the (RuntimeError, ValueError, OSError) the caller catches — or overwrite the value.
• Codex and Grok entries are built by a shared _as_toml_table helper rather than inline tomlkit calls. Same output shape.
• detect's name column is derived from the longest registered name instead of a hardcoded width, so every row of its output shifts by two spaces.

CLIInfo

The three things that actually vary per CLI are now declared rather than branched on:

Field	Meaning	Values in use
fmt	reader/writer selection	json, jsonc, toml
container	key path to the server map	("mcpServers",), ("mcp_servers",), ("mcp",)
dialect	shape of one entry	standard, claude, opencode

Both are required, so a CLI cannot be registered without deciding them. The full eight-row path table lives in scripts/README.md; the new rows are opencode → $XDG_CONFIG_HOME/opencode/opencode.jsonc (JSONC) and pi → ~/.pi/agent/mcp.json (JSONC — the suffix says JSON, but the adapter that reads it strips comments and allows trailing commas).

Design decisions

opencode's entry shape has no forgiving path. It takes {"type": "local", "command": [argv...], "environment": {...}}. A scalar command is a decode error that stops opencode starting at all, and an env key is accepted and then dropped in silence. Both spellings are pinned by tests rather than left to a round-trip assertion.

The array is split back apart on read. _spec_from_entry normalizes every dialect down to the portable scalar-command spec, so is_local_uv_directory, local_repo_path and pr_ref stay dialect-agnostic. This is not cosmetic: those helpers drive the "already local — no change" short-circuit, and without the split every invocation rewrites a config that was already correct.

JSONC is spliced, not reserialized. The JSON writer rebuilds the whole document, which for a commented file means deleting every comment in it. No PyPI JSONC parser gives JSONC what tomlkit gives TOML — a format-preserving round trip. The closest candidate, json-five, is unsafe here: given the JSON source {"a": "C:\\x"} it raises, and given {"a": "C:\\u0041"} it returns the 3-character C:A where the value is the 8-character C:\u0041. stdlib reads both correctly. A parser that quietly rewrites an untouched value is the failure this script exists to prevent, so the codec is stdlib plus a string-aware scanner.

Two carve-outs, both on a config with nothing to preserve: seeding an entry into a config that parsed empty also writes "$schema" (opencode injects that line itself on first load, so writing it avoids an immediate second edit), and a file with no content at all is generated rather than spliced.

opencode is user-scope only in the install picker. opencode mcp add resolves its target with resolveConfigPath(Global.Path.config, true) on the non-interactive path, so it writes the global config whichever scope was chosen. A Project panel would name a file the command it prints never touches.

pi is registered with its limitation stated, not hidden. The alternative was to leave pi out, since a config no agent reads is a swap that reports success and does nothing. Registering the path keeps the swap landing where the adapter looks, and the detect note keeps status honest about what an agent will actually run. If a pi-family agent that speaks MCP natively is ever needed, that is omp, not pi.

Test plan

• uv run ruff format ., uv run ruff check ., uv run mypy src tests, uv run pytest --reruns 0, just build-docs
• tests/test_mcp_swap.py — both new CLIs through set/get/delete; the opencode dialect in both directions including a PR spec; JSONC byte-fidelity across line and block comments, a trailing comma, an absent final newline, non-ASCII, // inside a URL, /* inside a string, a Windows path and a literal \u escape; comment survival including one inside the replaced entry; symlinked config; $schema seeding; the detect adapter note with and without the adapter present
• A guard test asserts the fake_home fixture covers every registered CLI — it replaces CLIS wholesale, so a CLI missing from it fails unrelated doctor tests with KeyError
• Manual: every registered CLI swapped and reverted byte-identically in one run against a sandboxed HOME and XDG_CONFIG_HOME, with doctor and status reading both new shapes back
• Manual: --pr, --dry-run, empty config, absent config, and replacing an entry that already carries an environment table
• Negative control: disabling the JSONC writer so jsonc falls through to the JSON one turns the comment-fidelity and byte-fidelity tests red

Sandboxing this script needs XDG_CONFIG_HOME set alongside HOME — opencode's path comes from the former, so a HOME-only sandbox reads and writes the real config. --dry-run prints the resolved path in its diff header.

references/cli-matrix.md gains a row per CLI: opencode's cells read "not yet verified" and pi's read n/a, since there is no MCP client to drive. That file's value is that every cell was confirmed against a running agent, and opencode has not been driven through the harness yet.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.93960% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.24%. Comparing base (34a5d9e) to head (e0433d0).

Files with missing lines	Patch %	Lines
scripts/mcp_swap.py	90.84%	17 Missing and 10 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #116      +/-   ##
==========================================
+ Coverage   85.39%   86.24%   +0.84%     
==========================================
  Files          46       46              
  Lines        3801     4042     +241     
  Branches      538      599      +61     
==========================================
+ Hits         3246     3486     +240     
+ Misses        408      404       -4     
- Partials      147      152       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.