Cowork Supervisor
dffa0e152f
Adds the user-facing half of the server catalog: a searchable, signed catalog browser wired to the existing paste/import path. bcc_core.py (pure, GUI-free, per the design comment on #10): - CATALOG_CATEGORY_GROUPS / catalog_category_group(): collapses the raw taxonomy to the 7 UI chips (unknown categories fall back to Other, never drop an entry). - catalog_entry_matches_query() / filter_catalog_entries() / catalog_entries_in_group(): search-as-you-type + category chip filtering over catalog entries. - format_freshness_hint(): last_release ISO date -> "Last updated N months/years ago", '' when missing/unparseable/future. - first_unfilled_focus_target(): finds the first <PLACEHOLDER> arg or blank env_required key so the GUI can focus it after Add. - load_bundled_catalog_entries(): reads+verifies+validates the bundled catalog.json/.sig pair, returns servers or an EMPTY list on ANY failure -- the load-bearing guarantee behind the dialog's empty state. - Bug fix: catalog_entry_to_paste_json() only copied config.env, ignoring env_required -- the field where 9 of the 19 seed entries (postgres, github, notion, obsidian, brave-search, tavily, home-assistant, n8n, grafana) actually declare their secret var names. Add would have silently added these servers with no env field for the user to fill in. Now env_required keys are seeded as empty-string placeholders unless config.env already sets them. bcc.py: - BrowseCatalogDialog: search box, category chips, list, detail pane (description/notes/homepage/freshness hint/verbatim command preview), per-tier action (Add for basic, Open setup docs for link-only). Every catalog-derived string goes through plain_label() (Qt.PlainText + html.escape, matching catalog_console.py's approach) or an inherently-plain QPlainTextEdit for the command preview -- catalog.json takes community PRs, so every field is attacker-influenceable. - "Browse catalog…" button next to Paste JSON. - ServerEditor.focus_target(): selects the first unfilled arg line or opens the env-table cell editor for the first blank env row. - Save-time placeholder guard: warns (Yes/No, defaults No) when any server still has an unfilled <PLACEHOLDER>; never blocks a deliberate save, never saves one unnoticed. bcc.spec: bundle data/catalog.json.sig alongside catalog.json -- the signature file was missing from datas, so a frozen build would have had a catalog.json with no matching .sig for resolve_catalog() to verify against. tests/test_core.py: +82 tests covering category-group mapping, catalog search/filter, freshness-hint formatting (including the month/year rounding boundary), first_unfilled_focus_target, the catalog_entry_to_paste_json env_required fix (incl. a regression against the real shipped postgres entry), and load_bundled_catalog_entries under valid/tampered/wrong-key/missing- file/invalid-but-signed conditions plus an end-to-end check against the real data/catalog.json + .sig (19 entries). GUI code (BrowseCatalogDialog, ServerEditor.focus_target, MainWindow.browse_catalog) is unavoidably untested here -- PySide6 cannot import in this sandbox (missing libEGL/system GL libs) -- but all the logic it depends on is pushed into bcc_core.py and covered above.
Better Claude Config (BCC)
A small, cross-platform GUI for editing the mcpServers block of Claude Desktop
and Claude Code 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.
Download (no Python required)
Pre-built self-contained binaries are attached to every GitHub Release:
| Platform | Download | Run |
|---|---|---|
| macOS | BetterClaudeConfig-macOS.zip |
Unzip → drag BetterClaudeConfig.app to Applications |
| Windows | BetterClaudeConfig-Windows.zip |
Unzip → double-click BetterClaudeConfig.exe |
| Linux | BetterClaudeConfig-Linux.tar.gz |
Extract → run BetterClaudeConfig |
macOS Gatekeeper note: the app is not notarized. On first launch, right-click → Open, or run
xattr -cr /Applications/BetterClaudeConfig.appin a terminal.
Verifying your download
BCC isn't code-signed — there's no budget for a paid certificate (macOS
Developer ID, Windows Authenticode). Instead, every release publishes a
SHA256SUMS file listing the checksum of each archive, detached-signed with
Ed25519 as SHA256SUMS.sig. Both are attached to the release alongside the
binaries.
What this proves: the file you downloaded is byte-for-byte what we published, and the manifest itself was signed by our release key.
What this does NOT do: it does not make the binary "safe," and it does not remove the macOS Gatekeeper or Windows SmartScreen warning — those are only suppressed by a paid OS-vendor certificate, which this project doesn't have. Verifying checksums is about detecting tampering in transit or on a mirror, not about vouching for the software.
Release signing public key (Ed25519, base64, raw 32 bytes):
<PLACEHOLDER — AJ: paste the public key from the Catalog Console (#62) here>
macOS / Linux
# From inside the folder you downloaded the release files into:
sha256sum -c SHA256SUMS
If your sha256sum complains about missing files, download SHA256SUMS
into the same directory as the archive you downloaded — it lists every
platform's archive, and only the one(s) present will be checked.
To also verify the manifest's signature (optional, requires Python +
pip install cryptography and a checkout of this repo):
python3 scripts/sign_checksums.py verify \
--sums SHA256SUMS --sig SHA256SUMS.sig \
--pubkey-b64 "<the public key above>"
Windows (PowerShell)
Get-FileHash .\BetterClaudeConfig-Windows.zip -Algorithm SHA256
Compare the printed hash (case-insensitively) against the matching line in
SHA256SUMS.
If a release has no SHA256SUMS.sig
The signing key is a repo secret that has to be configured manually; if a
release is missing the .sig file, the checksums themselves are still
valid and safe to check against — the release workflow only skips signing,
never checksum generation.
Run from source
pip install -r requirements.txt
python bcc.py
(Python 3.10+, PySide6 6.6+.)
What it does
-
Auto-discovers installs — scans the platform's app-support folder for any
Claude*directory (soClaudeandClaude-Workboth show up) and finds Claude Code's user-scope config at~/.claude.json(the fileclaude mcp addwrites). 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 — even broken JSON — drop in any snippet from an MCP doc (full
mcpServersblock, 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
.jsonfile 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
commandis 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
.appmay 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
Claude Desktop
| OS | Base it scans for Claude* |
|---|---|
| macOS | ~/Library/Application Support |
| Windows | %APPDATA% |
| Linux | ~/.config |
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.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).bcc.spec— PyInstaller build spec (cross-platform).scripts/build_icons.py— regeneratesicons/app.icnsandicons/app.icofrom source PNGs.scripts/sign_checksums.py— generates and Ed25519-signs the releaseSHA256SUMSmanifest (see Verifying your download).
Building from source
pip install -r requirements-dev.txt
python scripts/build_icons.py # regenerate icons if needed
pyinstaller bcc.spec
# macOS → dist/BetterClaudeConfig.app
# Windows → dist/BetterClaudeConfig.exe
# Linux → dist/BetterClaudeConfig
Releases are built automatically by GitHub Actions (.github/workflows/release.yml) when a version tag is pushed:
git tag v1.0.0 && git push --tags
Rebrand
The accent color is one constant (ACCENT) at the top of bcc.py.
License
MIT — see LICENSE.