release: v1.2.0 (#26) — merge #6/#8/#9/#17/#18/#19

# Conflicts:
#	bcc.py
#	bcc_core.py
#	tests/test_core.py

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: Lint (ruff)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format --check
+        run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    name: Tests (py${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      # bcc_core has no GUI imports, so the test suite needs no PySide6 —
+      # keeps CI fast and avoids Qt system-library headaches on the runner.
+      - name: Install test dependencies
+        run: pip install pytest
+
+      - name: Run tests
+        run: python -m pytest -v

.gitignore

@@ -5,6 +5,12 @@ __pycache__/
 .venv/
 venv/
 
+# Test / lint caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
 # PyInstaller / build
 build/
 dist/

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# Install once with: pip install pre-commit && pre-commit install
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json

CLAUDE.md

@@ -8,10 +8,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Install runtime dependency
 pip install -r requirements.txt
 python bcc.py          # run the GUI
-python test_core.py    # run unit tests (23 tests, no GUI needed)
+
+# Test & lint (no GUI / PySide6 needed — tests only exercise bcc_core)
+pip install -r requirements-dev.txt
+python -m pytest       # unit tests in tests/
+ruff check .           # lint
+ruff format .          # format (CI enforces ruff format --check)
 
 # Build a self-contained binary
-pip install -r requirements-dev.txt
 python scripts/build_icons.py   # regenerate icons/app.icns + icons/app.ico if needed
 pyinstaller bcc.spec
 # macOS  → dist/BetterClaudeConfig.app
@@ -19,7 +23,7 @@ pyinstaller bcc.spec
 # Linux  → dist/BetterClaudeConfig
 ```
 
-Requires Python 3.10+. Runtime dependency: `PySide6>=6.6`. Build-time: `pyinstaller>=6.0`, `pillow>=10.0`.
+Requires Python 3.10+. Runtime dependency: `PySide6>=6.6`. Tooling config (ruff, pytest, project metadata) lives in `pyproject.toml`. CI (`.github/workflows/ci.yml`) runs lint + tests on every push/PR; releases build on tag push (`release.yml`).
 
 ## Architecture
 
@@ -27,9 +31,9 @@ The codebase is split into two layers:
 
 **`bcc_core.py`** — All logic with no GUI imports. Contains:
 - `Profile` / `ServerEntry` dataclasses (the data model)
-- `discover_profiles()` — scans the platform's app-support directory for `Claude*` folders (Claude Desktop) **and** always adds `~/.claude/settings.json` (Claude Code, cross-platform)
+- `discover_profiles()` — scans the platform's app-support directory for `Claude*` folders (Claude Desktop) **and** always adds `~/.claude.json` (Claude Code user scope — what `claude mcp add` writes). `~/.claude/settings.json` is NOT a server config (it rejects `mcpServers` with a schema error) and is only surfaced, labelled legacy, if servers are found parked in it. Project-scope `.mcp.json` files can be opened via Add config…
 - `load_config` / `extract_servers` / `apply_servers` / `write_config` — the read/write pipeline; writes are atomic with rotating timestamped backups in `.bcc_backups/`
-- `parse_pasted_json()` — accepts three JSON shapes (full config, inner map, or bare server object)
+- `parse_pasted_json()` / `parse_pasted_json_verbose()` — accepts three JSON shapes (full config, inner map, or bare server object). Input does not have to be valid JSON: `repair_json_text()` auto-fixes markdown fences, surrounding prose, `//` `/* */` `#` comments, trailing/missing commas, smart quotes, single quotes, unquoted keys, Python/JS literals, and unclosed braces. The verbose variant also returns human-readable notes describing every repair applied (shown live in the paste dialog)
 - `check_dependency()` / `diagnostics_text()` / `pin_command_path()` — PATH resolution logic; distinguishes "found on normal PATH" (ok) vs "found only on augmented PATH" (warn) vs "not found" (missing). Uses an `lru_cache`-memoized `augmented_path()` that extends the inherited PATH with common runtime locations (nvm, homebrew, cargo, volta, etc.)
 - `test_remote()` — synchronous HTTP reachability check, intended to run off the UI thread
 

HANDOFF.md

@@ -0,0 +1,95 @@
+# HANDOFF — BCC feature backlog implementation
+
+For the Claude Code agent working in this repo. Read this whole file, then
+CLAUDE.md, before touching code. A supervising Claude session watches this
+project through the Gitea MCP (issues, PRs, CI runs on git.avezzano.io), so
+keep all state in Gitea where it can be seen: issues for work items, PRs for
+changes, comments for decisions.
+
+## Step 0 — sync state
+
+`main` may contain local commits that aren't on origin yet (the previous
+session couldn't push). Run `git status` / `git log origin/main..main`; if
+there are unpushed commits, **push them first** and confirm CI goes green
+before starting anything.
+
+## Step 1 — file the backlog as issues
+
+Create one Gitea issue per item in the backlog table below (`tea` CLI or the
+API — you have full credentials). Prefix titles with the ID (e.g.
+"[#2] Stdio server spawn-test"). Create labels P0/P1/P2 first if they don't
+exist. Copy each item's full section from `../bcc-feature-requests.md`
+(sibling of this repo folder) into the issue body — it has problem statements,
+evidence, proposed fixes, and acceptance criteria.
+
+**Corrections to that document — do not re-implement:**
+- "Doc correction: README Claude Code path" — DONE (commit `b16c0fd`).
+- Item 1 (secret masking) — MOSTLY DONE (commit `6dee318`): env/header values
+  masked via delegate + Show-secrets toggle, Add-dialog password echo,
+  diagnostics args redaction (`redact_args`). **Only remainder:** the warning
+  badge when a secret-shaped value sits in `args` instead of `env`. File the
+  issue scoped to just that.
+
+## Step 2 — work the backlog
+
+| Order | ID | Item | Priority | Notes |
+|---|---|---|---|---|
+| 1 | 2 | Stdio server spawn-test | P0 | Spawn with timeout, capture stderr; core logic in bcc_core (GUI-free, testable) |
+| 2 | 3 | Backup restore UI | P0 | List `.bcc_backups/`, preview/diff, restore through normal atomic-write path |
+| 3 | 4 | Stale-file protection | P0 | mtime/hash at load, re-check before write, prompt on conflict |
+| 4 | 1r | Secret-in-args warning badge | P0 | Remainder of item 1; `is_secret_key`/`_is_secret_value` already exist in bcc_core |
+| 5 | 8 | Duplicate-name conflict on paste/import | P1 | VERIFY FIRST: check `paste_json`/`dropEvent` in bcc.py for silent overwrite; file findings on the issue before coding |
+| 6 | 5 | Cross-client support (Cursor/Windsurf/VS Code) | P1 | VS Code uses `servers` not `mcpServers` — needs a read/write adapter, not just paths |
+| 7 | 6 | In-app MCP log viewer | P1 | Platform log paths in the doc |
+| 8 | 7 | Windows MSIX path detection | P1 | Can't test locally on macOS — unit-test the detection logic, note that in the PR |
+| 9 | 9 | Restart Claude Desktop button | P1 | Platform-specific process handling; scope to Desktop only |
+| 10 | 10 | Server catalog / one-click add | P2 | Design pass first — post a proposal as an issue comment before building |
+
+## Workflow rules
+
+- **Branch per issue** off `main`: `feat/<issue-number>-short-slug` (or
+  `fix/`). One issue per PR. Reference the issue in the PR description
+  (`Closes #N`).
+- **Before every commit:** `python -m pytest` (all green), `ruff check .`,
+  `ruff format .`. CI enforces all three.
+- **Conventional commits** (`feat:`, `fix:`, `test:`, `docs:`, `chore:`) —
+  match the existing history's style: body explains the why.
+- **Merge only with green CI.** If the supervising session has flagged
+  something on the PR, resolve it before merging.
+
+## Architecture guardrails (violating these fails review)
+
+1. **The cardinal rule:** config writes only ever touch `mcpServers` and
+   `_disabledMcpServers`. Every other key is preserved verbatim, in order.
+   This matters extra for `~/.claude.json`, which holds conversation history
+   and project state.
+2. **Core/GUI split:** all logic in `bcc_core.py` (no GUI imports, unit-
+   testable); `bcc.py` stays a thin PySide6 shell. New logic gets tests in
+   `tests/` — they run without PySide6, keep it that way.
+3. **No new runtime dependencies** without posting the justification on the
+   issue first. PySide6 is currently the only one.
+4. **Writes are atomic + backed up** — route any new disk writes through
+   `write_config()`.
+5. Secrets never appear in diagnostics output or logs — use `redact_args`/
+   `is_secret_key` from bcc_core.
+
+## Current state (as of this handoff)
+
+- **92 tests** in `tests/test_core.py`, ruff clean, CI = lint + pytest (py3.10/3.12).
+- `main` = `ece049c` (PR #16 merged). No unpushed commits.
+- **Completed items:** #2 (spawn-test, PR #11), #3 (backup restore UI, PR #14),
+  #4 (stale-file protection, PR #15), #1r (secret-in-args warning, PR #16).
+- **Next item:** #8 — duplicate-name conflict handling. **VERIFY FIRST:** read
+  `paste_json` and `dropEvent` in `bcc.py` to check whether pasting/dropping a
+  server with a name that already exists silently overwrites it; file your
+  findings as a comment on issue #8 before writing any code.
+- Recent features you should know exist: lenient JSON repair
+  (`repair_json_text`, `parse_pasted_json_verbose`, `repair_config_file` +
+  RepairDialog), ArgsEdit numbered gutter + `split_suspicious_args`,
+  resizable splitters with QSettings persistence, secret masking, Claude Code
+  profile at `~/.claude.json` (settings.json only as "legacy" when it holds
+  parked servers), backup restore UI (RestoreDialog, `list_backups`,
+  `backup_diff`, `restore_backup`), stale-file protection (StaleDialog,
+  `config_mtime`, `external_change_summary`).
+- GUI can't be smoke-tested in CI; note in each PR whether you ran
+  `python bcc.py` locally and what you checked.

README.md

@@ -32,12 +32,17 @@ python bcc.py
 
 - **Auto-discovers installs** — scans the platform's app-support folder for any
   `Claude*` directory (so `Claude` and `Claude-Work` both show up) **and** finds
-  Claude Code at `~/.claude/settings.json`. Use **Add config…** to point at any
-  other file manually.
+  Claude Code's user-scope config at `~/.claude.json` (the file `claude mcp add`
+  writes). Use **Add config…** to point at any other file manually — e.g. a
+  project's `.mcp.json`.
 - **Form-based editing** — name, command, args (one per line), env vars, or for
   remote servers: URL, transport, and headers. No raw JSON.
-- **Paste JSON** — drop in any snippet from an MCP doc (full `mcpServers` block,
-  inner map, or a single bare server object); it's parsed and merged.
+- **Paste JSON — even broken JSON** — drop in any snippet from an MCP doc (full
+  `mcpServers` block, inner map, or a single bare server object); it's parsed
+  and merged. The paste box parses as you type and auto-repairs the stuff docs
+  and chat windows love to break: markdown fences, surrounding prose, comments,
+  trailing or missing commas, smart quotes, single quotes, unquoted keys, and
+  unclosed braces — and tells you exactly what it fixed before you commit.
 - **Drag & drop** a `.json` file onto the window to import servers from it.
 - **Copy to ▸** — copy the selected server straight into your *other* install.
 - **Active / Disabled sections** — servers are shown in two labelled lists with
@@ -76,7 +81,9 @@ After saving, **restart that Claude install** for changes to take effect.
 | Windows | `%APPDATA%`                      |
 | Linux   | `~/.config`                      |
 
-**Claude Code** (all platforms): `~/.claude/settings.json`
+**Claude Code** (all platforms): `~/.claude.json` (user scope). If servers are
+found parked in `~/.claude/settings.json` — where Claude Code ignores them — that
+file is also listed, marked *legacy*, so you can copy them over.
 
 ## Files
 

bcc.spec

@@ -98,7 +98,7 @@ else:
         debug=False,
         bootloader_ignore_signals=False,
         strip=False,
-        upx=True,
+        upx=False,    # UPX can strip icon resources from the PE on Windows
         upx_exclude=[],
         runtime_tmpdir=None,
         console=False,

pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "better-claude-config"
+version = "1.2.0"
+description = "Cross-platform GUI for editing the mcpServers block of Claude Desktop and Claude Code configs"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "PySide6>=6.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "pre-commit>=3.5",
+]
+build = [
+    "pyinstaller>=6.0",
+    "pillow>=10.0",
+]
+
+[project.urls]
+Repository = "https://git.avezzano.io/the_og/better-claude-config"
+
+# ---------------------------------------------------------------------------
+# Tooling
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "SIM", # simplify
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501",   # line length handled pragmatically; GUI strings run long
+    "SIM108", # ternary rewrites hurt readability in places
+    "RUF001", # UI strings intentionally use typographic glyphs (−, →, ↳)
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"bcc.py" = ["F405", "F403"]  # Qt star-import style if ever used

requirements-dev.txt

@@ -4,3 +4,7 @@ PySide6>=6.6
 # Build / packaging
 pyinstaller>=6.0
 pillow>=10.0        # generates icons/app.ico during CI (Windows build)
+
+# Test / lint
+pytest>=8.0
+ruff>=0.6

scripts/build_icons.py

@@ -10,13 +10,11 @@ Requirements:
     pip install pillow          # for .ico
     iconutil                   # built into macOS; for .icns
 """
+
 from __future__ import annotations
 
-import os
-import platform
 import shutil
 import subprocess
-import sys
 import tempfile
 from pathlib import Path
 
@@ -32,22 +30,83 @@ def build_ico():
         print("Pillow not installed — skipping .ico generation (pip install pillow)")
         return
 
-    sizes = [16, 32, 48, 64, 128, 256]
-    imgs = []
+    import io
+    import struct
+
+    sizes = [16, 24, 32, 48, 64, 128, 256]
+    images: list[tuple[int, object]] = []
     for s in sizes:
         p = SRC / f"icon-{s}.png"
         if not p.exists():
             print(f"  Missing {p.name}, skipping")
             continue
-        imgs.append(Image.open(p).convert("RGBA"))
+        images.append((s, Image.open(p).convert("RGBA")))
 
-    if not imgs:
+    if not images:
         print("  No source PNGs found — cannot build .ico")
         return
 
+    # Write the ICO manually so that entries ≤ 128 px use uncompressed BMP DIB
+    # and the 256 px entry uses PNG.  Pillow's ICO saver stores all sizes as
+    # PNG-compressed ("Vista icon" format), which PyInstaller's Windows
+    # resource-updater cannot embed — it silently falls back to its default icon.
+
+    def bmp_dib(img: object) -> bytes:
+        """Return a BMP DIB (BITMAPINFOHEADER + BGRA rows + AND mask)."""
+        w, h = img.size
+        # biHeight is doubled: top half = XOR mask (color), bottom = AND mask
+        hdr = struct.pack(
+            "<IiiHHIIiiII",
+            40,  # biSize
+            w,
+            h * 2,  # biHeight (doubled per ICO convention)
+            1,  # biPlanes
+            32,  # biBitCount
+            0,  # biCompression (BI_RGB)
+            0,  # biSizeImage (0 ok for BI_RGB)
+            0,
+            0,
+            0,
+            0,
+        )
+        pix = img.load()
+        rows = bytearray()
+        for y in range(h - 1, -1, -1):  # bottom-up
+            for x in range(w):
+                r, g, b, a = pix[x, y]
+                rows += bytes([b, g, r, a])
+        # AND mask: 1 bit/pixel, rows padded to 32-bit boundary, all 0 (use alpha)
+        mask_row = ((w + 31) // 32) * 4
+        and_mask = bytes(mask_row * h)
+        return hdr + bytes(rows) + and_mask
+
+    def png_bytes(img: object) -> bytes:
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()
+
+    blobs: list[tuple[int, bytes]] = []
+    for s, img in images:
+        blobs.append((s, bmp_dib(img) if s < 256 else png_bytes(img)))
+
+    n = len(blobs)
+    dir_offset = 6 + n * 16  # ICONDIR (6) + n × ICONDIRENTRY (16)
+
+    out = bytearray()
+    out += struct.pack("<HHH", 0, 1, n)  # ICONDIR
+
+    cur = dir_offset
+    for s, blob in blobs:
+        w = h = s % 256  # 256 is stored as 0 in the byte field
+        out += struct.pack("<BBBBHHII", w, h, 0, 0, 1, 32, len(blob), cur)
+        cur += len(blob)
+
+    for _, blob in blobs:
+        out += blob
+
     dest = OUT / "app.ico"
-    imgs[-1].save(dest, format="ICO", append_images=imgs[:-1])
-    print(f"  Generated {dest.relative_to(ROOT)}  ({dest.stat().st_size // 1024 + 1} KB)")
+    dest.write_bytes(out)
+    print(f"  Generated {dest.relative_to(ROOT)}  ({len(out) // 1024 + 1} KB)")
 
 
 def build_icns():

test_core.py

@@ -1,92 +0,0 @@
-import json, tempfile, shutil
-from pathlib import Path
-import bcc_core as c
-
-tmp = Path(tempfile.mkdtemp())
-ok = []
-
-def check(name, cond):
-    ok.append(cond)
-    print(("PASS" if cond else "FAIL"), "-", name)
-
-# ---- 1. discovery (monkeypatch the base dir) ----
-base = tmp / "AppSupport"
-for d in ("Claude", "Claude-Work", "NotClaude"):
-    (base / d).mkdir(parents=True)
-(base / "Claude" / c.CONFIG_FILENAME).write_text("{}")
-# Claude-Work has no config yet; NotClaude shouldn't match
-c.app_support_base = lambda: base
-profs = c.discover_profiles()
-labels = sorted(p.label for p in profs)
-check("discovers Claude + Claude-Work, not NotClaude",
-      "Claude" in labels and "Claude-Work" in labels and "NotClaude" not in labels)
-check("flags missing config file", any(p.label=="Claude-Work" and not p.config_exists for p in profs))
-
-# ---- 2. write preserves OTHER keys + order, only touches mcpServers ----
-cfgpath = tmp / "real.json"
-original = {
-    "globalShortcut": "Cmd+Shift+Space",
-    "mcpServers": {"old": {"command": "node", "args": ["x.js"]}},
-    "someOtherTool": {"keep": True},
-}
-cfgpath.write_text(json.dumps(original, indent=2))
-cfg = c.load_config(cfgpath)
-servers = c.extract_servers(cfg)
-# add a new one, disable the old one
-servers.append(c.ServerEntry("brave", {"command": "npx", "args": ["-y", "@x/brave"]}, True))
-servers[0].enabled = False
-c.apply_servers(cfg, servers)
-c.write_config(cfgpath, cfg)
-written = json.loads(cfgpath.read_text())
-keys = list(written.keys())
-check("preserved globalShortcut", written.get("globalShortcut") == "Cmd+Shift+Space")
-check("preserved someOtherTool", written.get("someOtherTool") == {"keep": True})
-check("disabled server parked in _disabledMcpServers", "old" in written.get("_disabledMcpServers", {}))
-check("enabled server in mcpServers", "brave" in written.get("mcpServers", {}))
-check("old not in active mcpServers", "old" not in written.get("mcpServers", {}))
-check("key order kept (globalShortcut before mcpServers)", keys.index("globalShortcut") < keys.index("mcpServers"))
-check("backup created", (cfgpath.parent / c.BACKUP_DIRNAME).is_dir() and any((cfgpath.parent / c.BACKUP_DIRNAME).iterdir()))
-
-# ---- 3. paste parser, all shapes ----
-full = '{"mcpServers": {"a": {"command": "node", "args": ["a.js"]}}}'
-check("parse full config shape", list(c.parse_pasted_json(full)) == ["a"])
-inner = '{"b": {"command": "uvx", "args": ["mcp-server-git"]}}'
-check("parse inner block shape", list(c.parse_pasted_json(inner)) == ["b"])
-bare = '{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}'
-parsed = c.parse_pasted_json(bare)
-check("parse bare server + suggests name 'filesystem'", "filesystem" in parsed)
-remote = '{"url": "https://mcp.asana.com/sse"}'
-check("parse remote, suggests host name", "mcp" in c.parse_pasted_json(remote))
-try:
-    c.parse_pasted_json('{"junk": 5}')
-    check("rejects junk", False)
-except ValueError:
-    check("rejects junk", True)
-
-# ---- 4. validation ----
-bad = [c.ServerEntry("", {"command": "x"}, True),
-       c.ServerEntry("dup", {"command": "x"}, True),
-       c.ServerEntry("dup", {"command": "x"}, True),
-       c.ServerEntry("r", {"url": ""}, True),
-       c.ServerEntry("nocmd", {"command": ""}, True)]
-probs = c.validate_servers(bad)
-check("validation catches empty name", any("empty name" in p for p in probs))
-check("validation catches duplicate", any("Duplicate" in p for p in probs))
-check("validation catches missing url", any("no URL" in p for p in probs))
-check("validation catches missing command", any("no command" in p for p in probs))
-check("valid set passes clean", c.validate_servers([c.ServerEntry("good", {"command":"node"}, True)]) == [])
-
-# ---- 5. dependency check (python3 exists; bogusxyz does not) ----
-r_ok = c.check_dependency({"command": "python3"})
-check("dep check finds python3", r_ok["status"] == "ok")
-r_missing = c.check_dependency({"command": "definitely-not-real-binary-xyz"})
-check("dep check flags missing", r_missing["status"] == "missing")
-r_remote = c.check_dependency({"url": "https://example.com/mcp"})
-check("dep check marks remote", r_remote["status"] == "remote")
-# windows-style wrapper: cmd /c npx ...  -> should look past cmd to npx
-r_wrap = c.check_dependency({"command": "cmd", "args": ["/c", "definitely-not-real-xyz", "foo"]})
-check("dep check sees through shell wrapper", "definitely-not-real-xyz" in r_wrap["label"])
-
-print()
-print(f"{sum(ok)}/{len(ok)} passed")
-shutil.rmtree(tmp)

tests/test_json_repair.py

@@ -0,0 +1,253 @@
+"""Tests for the lenient JSON repair pipeline (repair_json_text +
+parse_pasted_json_verbose). Every case here is a shape people actually paste
+from MCP docs, blog posts, and chat windows."""
+
+import json
+
+import pytest
+
+import bcc_core as c
+
+GOOD = {"command": "npx", "args": ["-y", "@x/brave"]}
+
+
+def assert_brave(servers):
+    assert "brave" in servers
+    assert servers["brave"]["command"] == "npx"
+
+
+# --------------------------------------------------------------------------- #
+# Valid JSON passes through untouched
+# --------------------------------------------------------------------------- #
+def test_strict_json_no_notes():
+    servers, notes = c.parse_pasted_json_verbose('{"brave": {"command": "npx", "args": []}}')
+    assert_brave(servers)
+    assert notes == []
+
+
+# --------------------------------------------------------------------------- #
+# Markdown / prose wrappers
+# --------------------------------------------------------------------------- #
+def test_markdown_fence():
+    text = 'Add this to your config:\n```json\n{"brave": {"command": "npx"}}\n```\nThen restart.'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("fence" in n for n in notes)
+
+
+def test_fence_without_language_tag():
+    text = '```\n{"brave": {"command": "npx"}}\n```'
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+
+
+def test_prose_around_bare_json():
+    text = 'Paste the following: {"brave": {"command": "npx"}} and restart Claude.'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("before" in n or "after" in n for n in notes)
+
+
+# --------------------------------------------------------------------------- #
+# Comments
+# --------------------------------------------------------------------------- #
+def test_line_comments():
+    text = '{\n  // the search server\n  "brave": {"command": "npx"}\n}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("//" in n for n in notes)
+
+
+def test_block_comments():
+    text = '{ /* config */ "brave": {"command": "npx"} }'
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+
+
+def test_url_with_double_slash_is_not_a_comment():
+    text = '{"remote": {"url": "https://mcp.example.com/sse"}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert servers["remote"]["url"] == "https://mcp.example.com/sse"
+    assert notes == []
+
+
+# --------------------------------------------------------------------------- #
+# Commas
+# --------------------------------------------------------------------------- #
+def test_trailing_comma_object():
+    text = '{"brave": {"command": "npx", "args": ["-y"],},}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("trailing" in n for n in notes)
+
+
+def test_missing_comma_between_servers():
+    text = '{"brave": {"command": "npx"}\n"git": {"command": "uvx"}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert "brave" in servers and "git" in servers
+    assert any("missing comma" in n for n in notes)
+
+
+def test_missing_comma_between_string_fields():
+    text = '{"brave": {"command": "npx"\n"args": ["-y"]}}'
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert servers["brave"]["args"] == ["-y"]
+
+
+# --------------------------------------------------------------------------- #
+# Quotes
+# --------------------------------------------------------------------------- #
+def test_smart_quotes():
+    text = "{“brave”: {“command”: “npx”}}"
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("smart quotes" in n for n in notes)
+
+
+def test_single_quotes():
+    text = "{'brave': {'command': 'npx', 'args': ['-y']}}"
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("single-quoted" in n for n in notes)
+
+
+def test_single_quotes_with_inner_double():
+    text = """{'brave': {'command': 'npx', 'env': {'NOTE': 'say "hi"'}}}"""
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert servers["brave"]["env"]["NOTE"] == 'say "hi"'
+
+
+# --------------------------------------------------------------------------- #
+# JS-style laxness
+# --------------------------------------------------------------------------- #
+def test_unquoted_keys():
+    text = '{brave: {command: "npx", args: ["-y"]}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("bare object keys" in n for n in notes)
+
+
+def test_python_literals():
+    text = '{"brave": {"command": "npx", "enabled": True, "extra": None}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert servers["brave"]["enabled"] is True
+    assert servers["brave"]["extra"] is None
+    assert any("literals" in n for n in notes)
+
+
+# --------------------------------------------------------------------------- #
+# Structure damage
+# --------------------------------------------------------------------------- #
+def test_braceless_fragment():
+    text = '"brave": {"command": "npx", "args": ["-y"]}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("wrapped" in n for n in notes)
+
+
+def test_missing_closing_braces():
+    text = '{"mcpServers": {"brave": {"command": "npx", "args": ["-y"]'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("unclosed" in n for n in notes)
+
+
+def test_kitchen_sink():
+    # fence + comment + single quotes + unquoted key + trailing comma + prose
+    text = (
+        "Here's the config you need:\n"
+        "```json\n"
+        "{\n"
+        "  // brave search\n"
+        "  brave: {\n"
+        "    'command': 'npx',\n"
+        "    'args': ['-y', '@x/brave',],\n"
+        "  },\n"
+        "}\n"
+        "```\n"
+    )
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert servers["brave"]["args"] == ["-y", "@x/brave"]
+    assert len(notes) >= 4
+
+
+# --------------------------------------------------------------------------- #
+# Suspicious-args detection (several argv tokens typed on one line)
+# --------------------------------------------------------------------------- #
+def test_split_flag_and_value_on_one_line():
+    fixed, notes = c.split_suspicious_args(["--directory /path/to/server", "run", "main.py"])
+    assert fixed == ["--directory", "/path/to/server", "run", "main.py"]
+    assert len(notes) == 1
+
+
+def test_split_full_option_string():
+    fixed, notes = c.split_suspicious_args(["-y @pkg/server --port 8080"])
+    assert fixed == ["-y", "@pkg/server", "--port", "8080"]
+    assert notes
+
+
+def test_split_respects_quotes():
+    fixed, _ = c.split_suspicious_args(['--name "My Server"'])
+    assert fixed == ["--name", "My Server"]
+
+
+def test_split_leaves_legit_spaces_alone():
+    args = ["/Users/me/My Documents", "hello world", "run"]
+    fixed, notes = c.split_suspicious_args(args)
+    assert fixed == args
+    assert notes == []
+
+
+def test_split_leaves_clean_args_alone():
+    args = ["--directory", "/path/to/server", "run", "main.py"]
+    fixed, notes = c.split_suspicious_args(args)
+    assert fixed == args
+    assert notes == []
+
+
+# --------------------------------------------------------------------------- #
+# Config-file repair (load-time)
+# --------------------------------------------------------------------------- #
+def test_repair_config_file_fixes_and_reports(tmp_path):
+    p = tmp_path / "claude_desktop_config.json"
+    p.write_text(
+        '{\n  "globalShortcut": "Cmd+Space",\n'
+        "  // my servers\n"
+        '  "mcpServers": {\n'
+        '    "brave": {"command": "npx", "args": ["-y"],},\n'
+        "  },\n}"
+    )
+    cfg, notes, preview = c.repair_config_file(p)
+    assert cfg["mcpServers"]["brave"]["command"] == "npx"
+    assert cfg["globalShortcut"] == "Cmd+Space"  # unrelated keys survive
+    assert any("comment" in n for n in notes)
+    assert any("trailing" in n for n in notes)
+    assert json.loads(preview) == cfg
+    # nothing was written to disk
+    assert "//" in p.read_text()
+
+
+def test_repair_config_file_hopeless_raises(tmp_path):
+    p = tmp_path / "claude_desktop_config.json"
+    p.write_text("total nonsense, no braces at all")
+    with pytest.raises(ValueError):
+        c.repair_config_file(p)
+
+
+# --------------------------------------------------------------------------- #
+# Still fails cleanly on hopeless input
+# --------------------------------------------------------------------------- #
+def test_hopeless_input_raises_value_error():
+    with pytest.raises(ValueError):
+        c.parse_pasted_json_verbose("this is just prose with no json at all")
+
+
+def test_junk_object_still_rejected():
+    with pytest.raises(ValueError):
+        c.parse_pasted_json_verbose('{"junk": 5}')
+
+
+def test_empty_raises():
+    with pytest.raises(ValueError):
+        c.parse_pasted_json_verbose("   ")