Initial commit: Better Claude Config

2026-06-29 14:12:50 -04:00
commit 780d4c3a9c
7 changed files with 1832 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Better Claude Config (BCC)
+
+A small, cross-platform GUI for editing the `mcpServers` block of one or more
+Claude Desktop installs — without ever hand-writing JSON.
+
+BCC only ever touches `mcpServers` (and its own `_disabledMcpServers` parking
+key). Every other key in your config is preserved verbatim, in its original
+order. Each write is atomic and makes a timestamped backup first.
+
+## Install & run
+
+```bash
+pip install -r requirements.txt
+python bcc.py
+```
+
+(Python 3.10+.)
+
+## What it does
+
+- **Auto-discovers installs** — scans the platform's app-support folder for any
+  `Claude*` directory (so `Claude` and `Claude-Work` both show up), and lets you
+  **Add config…** to point at any file manually.
+- **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.
+- **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
+  live counts, so a server that's switched off in the config is obvious at a
+  glance. Toggle a server's checkbox to move it between sections (disabled
+  servers are parked under `_disabledMcpServers`, which Claude ignores).
+- **Dependency check + diagnostics** — each server shows whether its `command`
+  is actually found on PATH:
+  - ● green — found on the normal PATH; will work anywhere.
+  - ▲ amber (**PATH-risk**) — found, but *only* in a location BCC added on top of
+    the inherited PATH. It'll work when you launch Claude from a terminal, but a
+    double-clicked `.app` may not see it. This is the usual cause of "the tool
+    says it's fine but Claude won't start the server." One click on **Use full
+    path ↳** rewrites the bare command (`npx`) to its absolute path so any launch
+    finds it.
+  - ● red (**broken**) — not found anywhere.
+  - ◆ blue — remote (url) server. **Test connection** does a live reachability
+    check on a background thread (any HTTP response = reachable).
+
+  Each section header shows a **broken / PATH-risk count badge**, and selecting a
+  flagged server auto-opens a **Details** panel with a full, copy-pasteable
+  report: which command resolved to what, tailored install hints, and the exact
+  PATH that was searched (with `+` marking the dirs BCC added). **Re-check**
+  re-scans PATH after you install something; **Copy diagnostics** grabs the whole
+  report for a bug report.
+
+After saving, **restart that Claude install** for changes to take effect.
+
+## Config locations it scans
+
+| OS      | Base it scans for `Claude*`     |
+|---------|---------------------------------|
+| macOS   | `~/Library/Application Support`  |
+| Windows | `%APPDATA%`                      |
+| Linux   | `~/.config`                      |
+
+## Files
+
+- `bcc.py` — the GUI.
+- `bcc_core.py` — all the file/JSON/validation/dependency logic (no GUI deps).
+- `test_core.py` — unit suite for the core (`python test_core.py`).
+
+## Rebrand
+
+The accent color is one constant (`ACCENT`) at the top of `bcc.py`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).