# 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](../../releases):

| 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.app` in a terminal.

## Run from source

```bash
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 (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.
- **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
  `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
  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

**Claude Desktop**

| OS      | Base it scans for `Claude*`      |
|---------|----------------------------------|
| macOS   | `~/Library/Application Support`  |
| Windows | `%APPDATA%`                      |
| Linux   | `~/.config`                      |

**Claude Code** (all platforms): `~/.claude/settings.json`

## 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` — regenerates `icons/app.icns` and `icons/app.ico` from source PNGs.

## Building from source

```bash
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:

```bash
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](LICENSE).