Source code for google_scholar_search_mcp.cli.clients

"""Registering the server with MCP clients (Claude Desktop/Code, Cursor, ...)."""

from __future__ import annotations

import json
import os
import shutil
import subprocess
import sys
from pathlib import Path

from .constants import COMMAND_NAME, SERVER_NAME


[docs] def find_executable() -> str: """Locate the installed ``google-scholar-mcp`` command. Returns: str: Absolute path if found on ``PATH`` or via ``sys.argv[0]``, otherwise the bare command name. """ found = shutil.which(COMMAND_NAME) if found: return found candidate = Path(sys.argv[0]).resolve() if candidate.name.startswith(COMMAND_NAME): return str(candidate) return COMMAND_NAME
[docs] def claude_desktop_configs() -> list[Path]: """Find Claude Desktop config files for the current platform. Returns: list[Path]: Existing config files, or the platform default location if none exist. """ name = "claude_desktop_config.json" if sys.platform == "darwin": base = Path.home() / "Library" / "Application Support" elif sys.platform == "win32": base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) else: base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) candidates = [base / d / name for d in ("Claude", "Claude Desktop")] existing = [p for p in candidates if p.exists()] return existing or [candidates[0]]
[docs] def update_json_client(config_path: Path, command: str, label: str) -> bool: """Add or replace our entry under ``mcpServers`` in a JSON config file. Used for every client that stores MCP servers as JSON (Claude Desktop, Cursor, Windsurf, Gemini CLI). Other servers and keys are preserved; an existing ``env`` of our entry is kept. Args: config_path (Path): JSON config file; created if missing. command (str): Executable the client should launch. label (str): Client name used in the status message. Returns: bool: ``True`` if written, ``False`` if the file holds invalid JSON (it is left untouched). Raises: OSError: If the file cannot be read or written. """ config: dict = {} if config_path.exists(): try: config = json.loads(config_path.read_text(encoding="utf-8")) except json.JSONDecodeError: print(f" ! {config_path} is not valid JSON; not touching it") return False servers = config.setdefault("mcpServers", {}) existing_env = (servers.get(SERVER_NAME) or {}).get("env", {}) servers[SERVER_NAME] = { "command": command, **({"env": existing_env} if existing_env else {}), } config_path.parent.mkdir(parents=True, exist_ok=True) config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8") print(f" + {label}: {config_path}") return True
[docs] def update_claude_desktop(config_path: Path, command: str) -> bool: """Register the server in a Claude Desktop config file. Args: config_path (Path): ``claude_desktop_config.json`` location. command (str): Executable the client should launch. Returns: bool: ``True`` if the file was written, ``False`` if it holds invalid JSON. Raises: OSError: If the file cannot be read or written. """ return update_json_client(config_path, command, "Claude Desktop")
# MARK: Other # JSON-configured clients, written only if the app's directory exists # (so we never create config for software that is not installed).
[docs] def other_json_clients() -> list[tuple[str, Path]]: """List JSON-configured MCP clients besides Claude Desktop. Returns: list[tuple[str, Path]]: ``(label, config path)`` for Cursor, Windsurf and Gemini CLI; the files may not exist yet. """ home = Path.home() return [ ("Cursor", home / ".cursor" / "mcp.json"), ("Windsurf", home / ".codeium" / "windsurf" / "mcp_config.json"), ("Gemini CLI", home / ".gemini" / "settings.json"), ]
[docs] def existing_claude_code_entry() -> dict: """Read our user-scope Claude Code entry from ``~/.claude.json``. Returns: dict: The entry (``command``, ``args``, ``env``, ...), or ``{}`` if the file or entry is missing or unreadable. """ try: data = json.loads((Path.home() / ".claude.json").read_text(encoding="utf-8")) entry = data["mcpServers"][SERVER_NAME] return entry if isinstance(entry, dict) else {} except (OSError, ValueError, KeyError, TypeError): return {}
[docs] def existing_claude_code_env() -> dict[str, str]: """Read the env vars of our user-scope Claude Code entry. Returns: dict[str, str]: Variable names and values, empty if none. """ env = existing_claude_code_entry().get("env") if not isinstance(env, dict): return {} return {str(k): str(v) for k, v in env.items()}
def _claude_add_argv(claude: str, command: str, args: list, env: dict) -> list[str]: """Build the ``claude mcp add`` command line for our server. Args: claude (str): Path of the ``claude`` executable. command (str): Server executable to register. args (list): Arguments the server command takes. env (dict): Environment variables to set on the entry. Returns: list[str]: The argv list. """ env_args = [arg for k, v in env.items() for arg in ("-e", f"{k}={v}")] return [ claude, "mcp", "add", "--scope", "user", SERVER_NAME, *env_args, "--", command, *[str(a) for a in args], ] # fmt: skip
[docs] def update_claude_code(command: str) -> bool: """Register the server with Claude Code (user scope) if the CLI is present. An existing entry is replaced, but its env vars (proxy, delays, ...) are carried over so re-running ``setup`` never drops the user's settings. If the new registration fails, the previous entry is restored. Args: command (str): Server executable to register. Returns: bool: ``True`` if registered; ``False`` if the ``claude`` CLI is missing or registration failed. """ claude = shutil.which("claude") if not claude: return False old = existing_claude_code_entry() env = existing_claude_code_env() subprocess.run( # noqa: S603 - fixed argv, no shell [claude, "mcp", "remove", "--scope", "user", SERVER_NAME], capture_output=True, check=False, ) result = subprocess.run( # noqa: S603 _claude_add_argv(claude, command, [], env), capture_output=True, text=True, check=False, ) if result.returncode == 0: kept = f", kept {len(env)} env var(s)" if env else "" print(f" + Claude Code: registered (user scope{kept})") return True print(f" ! Claude Code registration failed: {result.stderr.strip()}") if isinstance(old.get("command"), str): # put the previous entry back restored = subprocess.run( # noqa: S603 _claude_add_argv( claude, old["command"], old.get("args") or [], {str(k): str(v) for k, v in (old.get("env") or {}).items()}, ), capture_output=True, check=False, ) state = "restored" if restored.returncode == 0 else "could NOT be restored" print(f" ! previous Claude Code entry {state}") return False