BCC Agent
38f14deeff
Fixes findings 2, 3, 4, 6, 7 from the issue #68 adversarial review. - Finding 2: config.env was type-checked only. Add CATALOG_DENIED_ENV_KEYS (case-insensitive) for interpreter/loader-override keys (NODE_OPTIONS, PYTHONPATH, LD_PRELOAD, ...), apply the ASCII check and the existing secret-value check to env keys/values, and require env values to be empty or a single <PLACEHOLDER> token. - Finding 3: version pinning was only checked by catalog_review.py (which never runs on the signing path per finding 1). Move enforcement into _validate_catalog_config: npm/uvx specs must carry @version or ==version (scoped names handled), docker images must have an explicit non-latest tag. Only the first plausible package-spec token is checked, so flags, <PLACEHOLDER>s, and docker subcommands/flags don't trip it. All 19 real catalog entries still validate clean. - Finding 4: the CI catalog-signature gate imported bcc_core from the PR branch and trusted whatever CATALOG_PUBKEYS said there, so a PR changing both catalog.json and CATALOG_PUBKEYS (with a matching signature) went green. ci.yml now hardcodes the expected base64 pubkey and asserts bcc_core.CATALOG_PUBKEYS matches it before verifying the signature. NOTE: the maintainer is planning to rotate this key -- update EXPECTED_CATALOG_PUBKEY_B64 in ci.yml as its own reviewed change when that happens, never bundled with a catalog content change. - Finding 6: resolve_catalog's anti-rollback/anti-freeze guards sat behind `if best_version >= 0`, so the first verified candidate was accepted unconditionally and the anti-freeze anchor drifted with each accepted candidate instead of staying fixed. The cap is now measured against the bundled catalog's version specifically (the trust anchor baked into the binary), regardless of evaluation order; bundled wins version ties; and a new pure `floor` parameter lets a future caller pass a persisted accepted-version floor. - Finding 7: catalog id is now constrained to ^[a-z0-9][a-z0-9._-]{0,63}$. Tests: fixed _minimal_catalog to use a pinned package (was enshrining finding 3), rewrote the env-passthrough test to prove the validation boundary instead of asserting env passes through unchecked, and reordered test_resolve_catalog_rejects_absurd_version_jump so it actually exercises the first-candidate path. Added positive/negative tests for every new rule. Manually verified each new check by commenting it out and confirming the guarding test goes red, then restoring it.
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.