[#5] Cross-client support (Cursor / Windsurf / VS Code) #5

New Issue

2026-07-02T00:50:03-04:00

the_og commented

2026-07-02 00:50:03 -04:00

Problem

BCC only discovers Claude Desktop and Claude Code. Research found this is a widely felt pain point — "each client has a different config file, a different path, and different behavior when something breaks." Config locations:

Cursor: ~/.cursor/mcp.json or per-project .cursor/mcp.json
Windsurf: ~/.codeium/windsurf/mcp_config.json
VS Code: servers top-level key (not mcpServers) — a real structural difference, not just a path difference

This is the headline feature of the leading competing tool (mcp-manager, 73 stars): "changes are automatically synced between Claude and Cursor."

Proposed solution

Extend discover_profiles() to scan for Cursor and Windsurf configs alongside the existing Claude Desktop scan.
Add a VS Code adapter that maps servers ↔ mcpServers on read/write (since BCC's internal model is keyed on mcpServers).
Copy to ▸ continues to work across all profiles — that is the natural payoff, since users maintain near-duplicate entries across clients today.

Acceptance criteria

Cursor (~/.cursor/mcp.json) and Windsurf configs appear in the profile dropdown alongside Claude ones.
VS Code's servers key round-trips correctly through load → edit → save.
All existing tests pass; new tests cover the new discovery paths and the VS Code adapter.

Relevant code

bcc_core.py::discover_profiles (line 83)
bcc_core.py::app_support_base (line 74)
bcc_core.py::extract_servers / apply_servers

## Problem BCC only discovers Claude Desktop and Claude Code. Research found this is a widely felt pain point — "each client has a different config file, a different path, and different behavior when something breaks." Config locations: - **Cursor**: `~/.cursor/mcp.json` or per-project `.cursor/mcp.json` - **Windsurf**: `~/.codeium/windsurf/mcp_config.json` - **VS Code**: `servers` top-level key (not `mcpServers`) — a real structural difference, not just a path difference This is the headline feature of the leading competing tool (`mcp-manager`, 73 stars): "changes are automatically synced between Claude and Cursor." ## Proposed solution 1. Extend `discover_profiles()` to scan for Cursor and Windsurf configs alongside the existing Claude Desktop scan. 2. Add a VS Code adapter that maps `servers` ↔ `mcpServers` on read/write (since BCC's internal model is keyed on `mcpServers`). 3. **Copy to ▸** continues to work across all profiles — that is the natural payoff, since users maintain near-duplicate entries across clients today. ## Acceptance criteria - Cursor (`~/.cursor/mcp.json`) and Windsurf configs appear in the profile dropdown alongside Claude ones. - VS Code's `servers` key round-trips correctly through load → edit → save. - All existing tests pass; new tests cover the new discovery paths and the VS Code adapter. ## Relevant code - `bcc_core.py::discover_profiles` (line 83) - `bcc_core.py::app_support_base` (line 74) - `bcc_core.py::extract_servers` / `apply_servers`

the_og added the P1 label 2026-07-02 00:50:03 -04:00

the_og commented

2026-07-04 16:52:51 -04:00

Scope/scheduling note (AJ): this is a behemoth — it gets its own branch, and it's a candidate to punt past the next release. Intent is to hold it until the app works exactly the way we want for the existing single-client (Claude Desktop / Claude Code) experience; cross-client generalization shouldn't happen on top of a UX that's still moving. Leaving it open and P1-labeled, but treat it as deferred / revisit-later, not next-release scope.

Scope/scheduling note (AJ): this is a **behemoth** — it gets its own branch, and it's a candidate to **punt past the next release**. Intent is to hold it until the app works exactly the way we want for the existing single-client (Claude Desktop / Claude Code) experience; cross-client generalization shouldn't happen on top of a UX that's still moving. Leaving it open and P1-labeled, but treat it as **deferred / revisit-later**, not next-release scope.

the_og commented

2026-07-08 12:02:44 -04:00

Design pass (Cowork supervisor)

The core problem

BCC currently hard-codes Claude's layout: mcpServers (+ our _disabledMcpServers parking key) in specific file locations. Other clients differ in path, top-level key, and sometimes schema:

Client	Config path(s)	Servers key	Notes
Claude Desktop	`claude_desktop_config.json`	`mcpServers`	current
Claude Code	`~/.claude.json` (user), project `.mcp.json`	`mcpServers`	current
Cursor	`~/.cursor/mcp.json` (global), project `.cursor/mcp.json`	`mcpServers`	same schema as Claude
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`	same schema
VS Code	`.vscode/mcp.json` / user `settings.json`	`servers`	different key and slightly different schema (per-server `type`, input variables)

Proposed architecture: a client-adapter model

Introduce a ClientSpec (adapter) that captures everything client-specific:

label, config-path discovery (global + project),
servers_key ("mcpServers" vs "servers"),
optional disabled_key (our parking key; may be per-client or unsupported),
to_internal(raw) / from_internal(entries) translation to/from BCC's ServerEntry model.

Everything else (the editor, tables, validation, backups, stale-file check, secret masking) works against the internal model and stays unchanged. The cardinal rule generalizes cleanly: the selective-write path already only rewrites the servers block + preserves every other key verbatim — parameterize it by servers_key and it holds for every client.

Discovery

Extend discover_profiles() to also scan each client's known locations; project-scoped files (Cursor/VS Code/Claude Code) can be surfaced via the existing "Add config…" and/or auto-detected in a user-chosen project dir.

Phasing (de-risked — do the refactor before adding clients)

Refactor to the adapter model with Claude Desktop + Claude Code as the first two adapters. Pure refactor, no behavior change, fully unit-tested. This is the keystone PR.
Add Cursor + Windsurf — same mcpServers schema, only new paths → low risk.
Add VS Code — different servers key + schema translation (type/inputs) → highest risk, do last, with its own translation layer + tests.

Risks / notes

VS Code's input-variable + type model is the only real schema-translation work; keep it isolated in that adapter.
Project-scoped .mcp.json discovery overlaps with a separate idea I flagged (auto-detecting Claude Code project configs) — worth unifying.
Per our earlier note: this feature is the trigger to revisit the BCC name (deferred until cross-client actually ships) — flagging, not acting.

Open decisions for you

Client priority — I'd do Cursor + Windsurf first (cheap), VS Code last. Agree?
Project configs — auto-detect in a chosen folder, or manual "Add config…" only to start?
Scope of phase 1 — I recommend landing the adapter refactor alone (no new clients) as one reviewed PR first, since it de-risks everything and is fully testable without any GUI.

This one is a genuine multi-PR effort (the issue rightly calls it a behemoth). If you greenlight phase 1, it's a well-bounded subagent task on its own branch.

## Design pass (Cowork supervisor) ### The core problem BCC currently hard-codes Claude's layout: `mcpServers` (+ our `_disabledMcpServers` parking key) in specific file locations. Other clients differ in **path**, **top-level key**, and sometimes **schema**: | Client | Config path(s) | Servers key | Notes | |--------|----------------|-------------|-------| | Claude Desktop | `claude_desktop_config.json` | `mcpServers` | current | | Claude Code | `~/.claude.json` (user), project `.mcp.json` | `mcpServers` | current | | Cursor | `~/.cursor/mcp.json` (global), project `.cursor/mcp.json` | `mcpServers` | same schema as Claude | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | same schema | | VS Code | `.vscode/mcp.json` / user `settings.json` | **`servers`** | different key **and** slightly different schema (per-server `type`, input variables) | ### Proposed architecture: a client-adapter model Introduce a `ClientSpec` (adapter) that captures everything client-specific: - `label`, config-path discovery (global + project), - `servers_key` (`"mcpServers"` vs `"servers"`), - optional `disabled_key` (our parking key; may be per-client or unsupported), - `to_internal(raw) / from_internal(entries)` translation to/from BCC's `ServerEntry` model. Everything else (the editor, tables, validation, backups, stale-file check, secret masking) works against the internal model and stays unchanged. **The cardinal rule generalizes cleanly**: the selective-write path already only rewrites the servers block + preserves every other key verbatim — parameterize it by `servers_key` and it holds for every client. ### Discovery Extend `discover_profiles()` to also scan each client's known locations; project-scoped files (Cursor/VS Code/Claude Code) can be surfaced via the existing "Add config…" and/or auto-detected in a user-chosen project dir. ### Phasing (de-risked — do the refactor before adding clients) 1. **Refactor to the adapter model** with Claude Desktop + Claude Code as the first two adapters. Pure refactor, **no behavior change**, fully unit-tested. This is the keystone PR. 2. **Add Cursor + Windsurf** — same `mcpServers` schema, only new paths → low risk. 3. **Add VS Code** — different `servers` key + schema translation (type/inputs) → highest risk, do last, with its own translation layer + tests. ### Risks / notes - VS Code's input-variable + `type` model is the only real schema-translation work; keep it isolated in that adapter. - Project-scoped `.mcp.json` discovery overlaps with a separate idea I flagged (auto-detecting Claude Code project configs) — worth unifying. - Per our earlier note: this feature is the trigger to revisit the **BCC name** (deferred until cross-client actually ships) — flagging, not acting. ### Open decisions for you 1. **Client priority** — I'd do Cursor + Windsurf first (cheap), VS Code last. Agree? 2. **Project configs** — auto-detect in a chosen folder, or manual "Add config…" only to start? 3. Scope of phase 1 — I recommend landing the **adapter refactor alone** (no new clients) as one reviewed PR first, since it de-risks everything and is fully testable without any GUI. This one is a genuine multi-PR effort (the issue rightly calls it a behemoth). If you greenlight phase 1, it's a well-bounded subagent task on its own branch.

the_og commented

2026-07-12 13:58:20 -04:00

Design pass (2026-07-12) — proposed for next week's release

Model: client adapters over the existing Profile system. A client = {label, per-platform config paths, discovery rule, shape adapter}. BCC's whole pipeline (load → extract → edit → apply → atomic write with backups) already only assumes "JSON file with a servers map", so most of the work is discovery + one shape translation.

Phase 1 — Cursor + Windsurf (low risk, same shape):

Cursor: ~/.cursor/mcp.json (global) and <project>/.cursor/mcp.json — top-level mcpServers, byte-compatible with what BCC edits today.
Windsurf: ~/.codeium/windsurf/mcp_config.json — also mcpServers.
Work: add both to discover_profiles() (labels "Cursor", "Windsurf"), gate Desktop-only actions (Restart button already gated by filename). Copy to ▸ across clients then works for free. Project-scope Cursor configs can reuse the #53 pattern once we have a project list source (start with Add config… only).
Risk: none structural — same cardinal rule (only touch mcpServers + bcc keys, preserve the rest).

Phase 2 — VS Code (shape translation):

.vscode/mcp.json / user settings.json use a different shape: {"servers": {name: {...}}}, with type values and input-variable placeholders (${input:...}).
Work: a ShapeAdapter pair (to_entries(cfg) / apply_entries(cfg, servers)) keyed off the profile; identity adapter for everything current, VS Code adapter mapping servers ⇄ mcpServers and leaving inputs untouched. settings.json is JSONC — the existing repair pipeline already strips comments, but we must not rewrite the whole settings.json (it's shared with everything else in VS Code); v1: support .vscode/mcp.json and the dedicated user mcp.json only, explicitly skip settings.json-embedded config.

Suggested sequencing: Phase 1 lands early next week (small, testable), Phase 2 as its own PR behind it. Naming/rebrand question stays deferred per the recorded decision until this actually ships.

## Design pass (2026-07-12) — proposed for next week's release **Model: client adapters over the existing Profile system.** A client = `{label, per-platform config paths, discovery rule, shape adapter}`. BCC's whole pipeline (load → extract → edit → apply → atomic write with backups) already only assumes "JSON file with a servers map", so most of the work is discovery + one shape translation. **Phase 1 — Cursor + Windsurf (low risk, same shape):** - Cursor: `~/.cursor/mcp.json` (global) and `<project>/.cursor/mcp.json` — top-level `mcpServers`, byte-compatible with what BCC edits today. - Windsurf: `~/.codeium/windsurf/mcp_config.json` — also `mcpServers`. - Work: add both to `discover_profiles()` (labels "Cursor", "Windsurf"), gate Desktop-only actions (Restart button already gated by filename). `Copy to ▸` across clients then works for free. Project-scope Cursor configs can reuse the #53 pattern once we have a project list source (start with Add config… only). - Risk: none structural — same cardinal rule (only touch `mcpServers` + bcc keys, preserve the rest). **Phase 2 — VS Code (shape translation):** - `.vscode/mcp.json` / user `settings.json` use a **different shape**: `{"servers": {name: {...}}}`, with `type` values and input-variable placeholders (`${input:...}`). - Work: a `ShapeAdapter` pair (`to_entries(cfg)` / `apply_entries(cfg, servers)`) keyed off the profile; identity adapter for everything current, VS Code adapter mapping `servers` ⇄ `mcpServers` and leaving `inputs` untouched. `settings.json` is JSONC — the existing repair pipeline already strips comments, but we must **not rewrite the whole settings.json** (it's shared with everything else in VS Code); v1: support `.vscode/mcp.json` and the dedicated user `mcp.json` only, explicitly skip `settings.json`-embedded config. **Suggested sequencing:** Phase 1 lands early next week (small, testable), Phase 2 as its own PR behind it. Naming/rebrand question stays deferred per the recorded decision until this actually ships.

the_og referenced this issue

2026-07-12 13:58:30 -04:00

[#10] Server catalog / one-click add — design pass first #10

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: the_og/better-claude-config#5