feat(clients): fall back to ~/.claude.json when the claude CLI is absent (#463)

[dsarno]

Summary

Closes #463.

When Claude Code is installed only as a VS Code / Cursor extension, there's no claude binary on PATH. The claude_code descriptor is a cli-type client, so the CLI strategy couldn't find the binary → the dock showed it red and Configure failed with "Claude Code not found". As the reporter found, the workaround is to hand-edit ~/.claude.json:

"mcpServers": { "godot-ai": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } }

…which is exactly what claude mcp add --scope user --transport http writes anyway.

Fix

Make claude_code a CLI-preferred client with a JSON fallback:

• It now also declares where its config lives (~/.claude.json, mcpServers, type: "http").
• When the claude binary resolves, everything behaves exactly as before (CLI path — no change for users who have it).
• When the binary is absent, Configure / Remove / status route through the shared, well-tested JSON read-merge-write strategy (_json_strategy.gd) instead, producing the same entry the CLI would. The dot turns green and Configure works with no manual editing.

The JSON strategy parses the full file, mutates only the godot-ai entry, and writes it back atomically — all other content in ~/.claude.json (projects, history, other MCP servers) is preserved, and it refuses to overwrite a file it can't safely round-trip.

Changes

• _base.gd — has_json_fallback() capability flag; is_installed() honours it (a fallback client counts as installed when its config file exists, fixing the "(not detected)" label).
• claude_code.gd — declare path_template / server_key_path / entry_extra_fields for the fallback.
• client_configurator.gd — route cli dispatch (configure/remove/status + the dock's status-probe shortcut) to the JSON strategy when the binary isn't resolvable.
• test_clients.gd — cover has_json_fallback() semantics, the claude_code descriptor, and a full fallback dispatch round-trip (configure → CONFIGURED → preserves unrelated servers → remove → NOT_CONFIGURED).

Generality

has_json_fallback() is generic — any future CLI client whose CLI just writes a known JSON file can opt in by declaring path_template + server_key_path. Only claude_code does today.

Testing

• script/ci-check-gdscript → All GDScript files OK.
• Ran the clients suite headless against a live editor: 92 passed / 0 failed, including the three new tests.

https://claude.ai/code/session_01Jq5X4ivngAf1N6r5UX2BVw

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!