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

Claude Code installed only as a VS Code/Cursor extension exposes no 'claude'
binary on PATH, so the CLI strategy reported it red and Configure failed —
even though 'claude mcp add --scope user' just writes an mcpServers entry into
~/.claude.json, which the user can (and did) add by hand.

Make claude_code a CLI-preferred client with a JSON fallback: it declares its
config location (~/.claude.json, mcpServers, type:http) and, when the binary
isn't resolvable, Configure/Remove/status route through the shared JSON
read-merge-write strategy instead. The CLI remains the primary path whenever it
resolves, so nothing changes for users who have it. The fallback only triggers
on a missing binary and preserves all other content in ~/.claude.json.

- _base.gd: has_json_fallback() capability; is_installed() honours it.
- claude_code.gd: declare path_template / server_key_path / entry_extra_fields.
- client_configurator.gd: route cli dispatch to JSON when the binary is absent.
- test_clients.gd: cover the fallback dispatch, descriptor, and semantics.

Closes #463.

https://claude.ai/code/session_01Jq5X4ivngAf1N6r5UX2BVw

Author: claude

plugin/addons/godot_ai/client_configurator.gd

@@ -206,7 +206,11 @@ static func check_status_details_for_url_with_cli_path(id: String, url: String,
 	var client := ClientRegistry.get_by_id(id)
 	if client == null:
 		return {"status": Client.Status.NOT_CONFIGURED, "error_msg": ""}
-	if client.config_type == "cli" and cli_path.is_empty():
+	# A cli client with no resolved binary normally reads as NOT_CONFIGURED.
+	# Skip that shortcut when the client has a JSON fallback (#463): the
+	# dispatch below reads its config file directly so the status dot reflects
+	# a fallback-configured entry instead of always showing red.
+	if client.config_type == "cli" and cli_path.is_empty() and not client.has_json_fallback():
 		return {"status": Client.Status.NOT_CONFIGURED, "error_msg": ""}
 	return _dispatch_check_status_with_cli_path_details(client, url, cli_path)
 
@@ -219,7 +223,9 @@ static func client_status_probe_snapshot(id: String) -> Dictionary:
 	var installed := false
 	if client.config_type == "cli":
 		cli_path = CliStrategy.resolve_cli_path(client)
-		installed = not cli_path.is_empty()
+		# #463: a JSON-fallback cli client (Claude Code as a VS Code extension)
+		# is "installed" when its fallback config exists, even with no binary.
+		installed = not cli_path.is_empty() or client.is_installed()
 	else:
 		installed = client.is_installed()
 	return {"id": id, "cli_path": cli_path, "installed": installed}
@@ -247,6 +253,10 @@ static func _dispatch_configure(client: Client, url: String) -> Dictionary:
 		"toml":
 			return TomlStrategy.configure(client, SERVER_NAME, url)
 		"cli":
+			# #463: fall back to writing the config file directly when the CLI
+			# binary isn't on PATH (Claude Code as a VS Code/Cursor extension).
+			if client.has_json_fallback() and CliStrategy.resolve_cli_path(client).is_empty():
+				return JsonStrategy.configure(client, SERVER_NAME, url)
 			return CliStrategy.configure(client, SERVER_NAME, url)
 	return {"status": "error", "message": "Unknown config_type for %s: %s" % [client.id, client.config_type]}
 
@@ -258,6 +268,10 @@ static func _dispatch_remove(client: Client) -> Dictionary:
 		"toml":
 			return TomlStrategy.remove(client, SERVER_NAME)
 		"cli":
+			# #463: mirror the configure fallback so Remove also works without
+			# the CLI binary — otherwise a fallback-written entry is unremovable.
+			if client.has_json_fallback() and CliStrategy.resolve_cli_path(client).is_empty():
+				return JsonStrategy.remove(client, SERVER_NAME)
 			return CliStrategy.remove(client, SERVER_NAME)
 	return {"status": "error", "message": "Unknown config_type for %s: %s" % [client.id, client.config_type]}
 
@@ -277,9 +291,12 @@ static func _dispatch_check_status_with_cli_path_details(client: Client, url: St
 		"toml":
 			return {"status": TomlStrategy.check_status(client, SERVER_NAME, url), "error_msg": ""}
 		"cli":
-			if cli_path.is_empty():
-				return CliStrategy.check_status_details(client, SERVER_NAME, url, CliStrategy.resolve_cli_path(client))
-			return CliStrategy.check_status_details(client, SERVER_NAME, url, cli_path)
+			var resolved_cli := cli_path if not cli_path.is_empty() else CliStrategy.resolve_cli_path(client)
+			# #463: with no CLI binary, read the JSON fallback config so a
+			# fallback-configured entry reports CONFIGURED instead of red.
+			if resolved_cli.is_empty() and client.has_json_fallback():
+				return {"status": JsonStrategy.check_status(client, SERVER_NAME, url), "error_msg": ""}
+			return CliStrategy.check_status_details(client, SERVER_NAME, url, resolved_cli)
 	return {"status": Client.Status.NOT_CONFIGURED, "error_msg": ""}
 
 

plugin/addons/godot_ai/clients/_base.gd

@@ -120,10 +120,27 @@ func resolved_config_path() -> String:
 	return McpPathTemplate.resolve(path_template)
 
 
+## True when a CLI client also declares where its config file lives, so it can
+## fall back to writing that file directly when the CLI binary isn't on PATH.
+## #463: Claude Code installed only as a VS Code / Cursor extension exposes no
+## `claude` binary, but `claude mcp add --scope user` just writes `mcpServers`
+## into ~/.claude.json — so we can produce the same entry ourselves.
+func has_json_fallback() -> bool:
+	return config_type == "cli" and not path_template.is_empty() and not server_key_path.is_empty()
+
+
 ## True if the user appears to have this client installed locally.
 func is_installed() -> bool:
 	if config_type == "cli":
-		return not McpCliFinder.find(_array_from_packed(cli_names)).is_empty()
+		if not McpCliFinder.find(_array_from_packed(cli_names)).is_empty():
+			return true
+		# CLI not on PATH. A cli client with a JSON fallback (Claude Code as a
+		# VS Code/Cursor extension, #463) still counts as installed if its
+		# fallback config file already exists.
+		if has_json_fallback():
+			var cfg := resolved_config_path()
+			return not cfg.is_empty() and FileAccess.file_exists(cfg)
+		return false
 	for p in detect_paths:
 		var resolved := McpPathTemplate.expand(p)
 		if not resolved.is_empty() and (FileAccess.file_exists(resolved) or DirAccess.dir_exists_absolute(resolved)):

plugin/addons/godot_ai/clients/claude_code.gd

@@ -13,3 +13,12 @@ func _init() -> void:
 	)
 	cli_unregister_template = PackedStringArray(["mcp", "remove", "{name}"])
 	cli_status_args = PackedStringArray(["mcp", "list"])
+	## #463: JSON fallback for when the `claude` binary isn't on PATH — e.g.
+	## Claude Code installed only as a VS Code / Cursor extension. The CLI is
+	## still preferred whenever it resolves; this is what gets written
+	## otherwise. `claude mcp add --scope user --transport http` produces
+	## exactly this shape under `mcpServers` in ~/.claude.json:
+	##   "godot-ai": { "type": "http", "url": "<url>" }
+	path_template = {"unix": "~/.claude.json", "windows": "~/.claude.json"}
+	server_key_path = PackedStringArray(["mcpServers"])
+	entry_extra_fields = {"type": "http"}

test_project/tests/test_clients.gd

@@ -715,6 +715,81 @@ func test_json_strategy_round_trip() -> void:
 	assert_eq(McpJsonStrategy.check_status(client, "godot-ai", "http://127.0.0.1:8000/mcp"), McpClient.Status.NOT_CONFIGURED)
 
 
+## #463: a CLI client (Claude Code) installed only as a VS Code/Cursor
+## extension has no `claude` binary on PATH. With a JSON fallback declared,
+## Configure/Remove/status must route through the config file directly.
+func _make_cli_json_fallback_client(path: String) -> McpClient:
+	var c := McpClient.new()
+	c.id = "cli_fallback_test"
+	c.display_name = "CLI Fallback Test"
+	c.config_type = "cli"
+	# A binary name that will never resolve on PATH, forcing the fallback.
+	c.cli_names = PackedStringArray(["godot-ai-nonexistent-cli-xyz"])
+	c.cli_register_template = PackedStringArray(["mcp", "add", "{name}", "{url}"])
+	c.cli_unregister_template = PackedStringArray(["mcp", "remove", "{name}"])
+	c.path_template = {"darwin": path, "windows": path, "linux": path, "unix": path}
+	c.server_key_path = PackedStringArray(["mcpServers"])
+	c.entry_extra_fields = {"type": "http"}
+	return c
+
+
+func test_has_json_fallback_semantics() -> void:
+	var path := _scratch_dir.path_join("fallback_sem.json")
+	var with_fallback := _make_cli_json_fallback_client(path)
+	assert_true(with_fallback.has_json_fallback(), "cli client with path_template + server_key_path should report a JSON fallback")
+	var no_path := _make_cli_json_fallback_client(path)
+	no_path.path_template = {}
+	assert_false(no_path.has_json_fallback(), "cli client without path_template should not report a JSON fallback")
+	# JSON-config clients are not "cli fallbacks".
+	assert_false(_make_test_json_client(path).has_json_fallback(), "a plain json client should not report a cli JSON fallback")
+
+
+func test_claude_code_has_claude_json_fallback() -> void:
+	var client := McpClientRegistry.get_by_id("claude_code")
+	assert_true(client != null, "claude_code must be registered")
+	assert_eq(client.config_type, "cli")
+	assert_true(client.has_json_fallback(), "claude_code should declare a ~/.claude.json fallback (#463)")
+	assert_eq(client.server_key_path.size(), 1)
+	assert_eq(client.server_key_path[0], "mcpServers")
+	assert_eq(client.entry_extra_fields.get("type"), "http", "claude mcp add --transport http writes type:http")
+	assert_true(client.resolved_config_path().ends_with(".claude.json"), "fallback path should be ~/.claude.json, got %s" % client.resolved_config_path())
+
+
+func test_cli_fallback_dispatch_writes_json_when_binary_missing() -> void:
+	var path := _scratch_dir.path_join("cli_fallback.json")
+	_remove_if_exists(path)
+	# Pre-seed an unrelated server that must survive the fallback write.
+	var seed := {"mcpServers": {"someone-else": {"url": "http://other/"}}}
+	var f := FileAccess.open(path, FileAccess.WRITE)
+	f.store_string(JSON.stringify(seed))
+	f.close()
+
+	var client := _make_cli_json_fallback_client(path)
+	# The bogus cli_names never resolve, so dispatch must take the JSON fallback.
+	var result := McpClientConfigurator._dispatch_configure(client, "http://127.0.0.1:8000/mcp")
+	assert_eq(result.get("status"), "ok", "fallback configure should succeed: %s" % result.get("message", ""))
+
+	var status := McpClientConfigurator._dispatch_check_status_with_cli_path_details(client, "http://127.0.0.1:8000/mcp", "")
+	assert_eq(status.get("status"), McpClient.Status.CONFIGURED, "fallback-configured entry should read CONFIGURED")
+
+	# The written entry carries type:http + url, and the other server survives.
+	var read_file := FileAccess.open(path, FileAccess.READ)
+	var json := JSON.new()
+	assert_eq(json.parse(read_file.get_as_text()), OK)
+	read_file.close()
+	var servers: Dictionary = json.data["mcpServers"]
+	assert_true(servers.has("someone-else"), "unrelated server entry must be preserved")
+	var entry: Dictionary = servers["godot-ai"]
+	assert_eq(entry.get("type"), "http", "fallback entry should pin type:http")
+	assert_eq(entry.get("url"), "http://127.0.0.1:8000/mcp")
+
+	# Remove also goes through the fallback so the entry stays removable.
+	var removed := McpClientConfigurator._dispatch_remove(client)
+	assert_eq(removed.get("status"), "ok")
+	var after := McpClientConfigurator._dispatch_check_status_with_cli_path_details(client, "http://127.0.0.1:8000/mcp", "")
+	assert_eq(after.get("status"), McpClient.Status.NOT_CONFIGURED, "removed fallback entry should read NOT_CONFIGURED")
+
+
 func test_json_strategy_preserves_other_servers() -> void:
 	var path := _scratch_dir.path_join("preserve.json")
 	# Pre-seed the file with another server entry that must survive.