cli

Command line entry point (google-scholar-mcp): serve, setup and install-skill.

Command line entry point: run the server, configure clients, install the skill.

google-scholar-mcp with no arguments still starts the stdio server, so MCP client configs written before these subcommands existed keep working.

google_scholar_search_mcp.cli.setup(args)[source]

Register the server with detected MCP clients and install the skill.

Parameters:

args (argparse.Namespace) – Parsed setup options (no_claude_desktop, no_claude_code, no_skill, force, target).

Returns:

int – Exit code, 0 if something was configured, 1 if not.

Return type:

int

google_scholar_search_mcp.cli.main(argv=None)[source]

Run the google-scholar-mcp command.

Without a subcommand (or with serve) the stdio MCP server starts.

Parameters:

argv (list[str] | None) – Arguments; None means sys.argv[1:].

Returns:

None – setup and install-skill end the process via SystemExit; serve blocks until the client disconnects.

Raises:

SystemExit – With the command’s exit code, or 2 on invalid arguments.

Return type:

None

clients

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

google_scholar_search_mcp.cli.clients.find_executable()[source]

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.

Return type:

str

google_scholar_search_mcp.cli.clients.claude_desktop_configs()[source]

Find Claude Desktop config files for the current platform.

Returns:

list[Path] – Existing config files, or the platform default location if none exist.

Return type:

list[Path]

google_scholar_search_mcp.cli.clients.update_json_client(config_path, command, label)[source]

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.

Parameters:
  • 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.

Return type:

bool

google_scholar_search_mcp.cli.clients.update_claude_desktop(config_path, command)[source]

Register the server in a Claude Desktop config file.

Parameters:
  • 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 type:

bool

google_scholar_search_mcp.cli.clients.other_json_clients()[source]

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.

Return type:

list[tuple[str, Path]]

google_scholar_search_mcp.cli.clients.existing_claude_code_entry()[source]

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.

Return type:

dict

google_scholar_search_mcp.cli.clients.existing_claude_code_env()[source]

Read the env vars of our user-scope Claude Code entry.

Returns:

dict[str, str] – Variable names and values, empty if none.

Return type:

dict[str, str]

google_scholar_search_mcp.cli.clients.update_claude_code(command)[source]

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.

Parameters:

command (str) – Server executable to register.

Returns:

bool – True if registered; False if the claude CLI is missing or registration failed.

Return type:

bool

targets

Per-agent skill destinations (Claude, Cursor, Windsurf, AGENTS.md, Gemini).

google_scholar_search_mcp.cli.targets.shared_skill(root, content, force)[source]

Write the full skill to .agents/skills for pointer blocks to refer to.

Parameters:
  • root (Path) – Project directory.

  • content (str) – Full SKILL.md text.

  • force (bool) – Overwrite a differing existing file.

Returns:

tuple[str, Path] – Write status and the skill file path.

Raises:

OSError – If the file cannot be written.

Return type:

tuple[str, Path]

google_scholar_search_mcp.cli.targets.pointer_block(skill_path, root, description)[source]

Build the short marked block that points an agent at the skill file.

Parameters:
  • skill_path (Path) – Location of the full skill; must be inside root.

  • root (Path) – Project directory the path is made relative to.

  • description (str) – One-line skill description shown in the block.

Returns:

str – Markdown block including the BEGIN/END markers.

Raises:

ValueError – If skill_path is not inside root.

Return type:

str

google_scholar_search_mcp.cli.targets.detect_targets(root)[source]

List the agents that appear to be used in a project.

Parameters:

root (Path) – Project directory to inspect.

Returns:

list[str] – Names from TARGETS whose marker file or directory exists (claude-user is always included).

Return type:

list[str]

google_scholar_search_mcp.cli.targets.install_skill(targets=None, root=None, force=False)[source]

Install the skill into several agents.

Never overwrites a differing file unless force is set. Per-target write errors are printed and reported as "error" instead of raised.

Parameters:
  • targets (list[str] | None) – Names from TARGETS; None means every detected agent.

  • root (Path | None) – Project directory (default: current directory).

  • force (bool) – Overwrite differing files.

Returns:

list[tuple[str, str, Path | None]] – (target, status, path) per target, status being installed, current, skipped or error (path is None on error).

Raises:

KeyError – If a name in targets is not in TARGETS.

Return type:

list[tuple[str, str, Path | None]]

skill

Fetching the skill and writing it without clobbering user files.

google_scholar_search_mcp.cli.skill.bundled_skill()[source]

Read the SKILL.md shipped inside the package.

Returns:

str – Full text of the bundled SKILL.md.

Raises:

FileNotFoundError – If the package was built without the skill file.

Return type:

str

google_scholar_search_mcp.cli.skill.fetch_skill(url, timeout=10.0)[source]

Download the skill, falling back to the bundled copy.

Any failure (network, TLS, 404, non-https URL, content that does not look like a SKILL.md) is reported on stdout and never raised.

Parameters:
  • url (str | None) – https URL of a SKILL.md, or None to use the bundled copy directly.

  • timeout (float) – Download timeout in seconds.

Returns:

tuple[str, str] – The skill text and where it came from (the URL or "bundled copy").

Return type:

tuple[str, str]

google_scholar_search_mcp.cli.skill.split_skill(content)[source]

Split a SKILL.md into its description and body.

Parameters:

content (str) – Full SKILL.md text including frontmatter.

Returns:

tuple[str, str] – The description frontmatter value (a generic fallback if missing) and the text after the frontmatter.

Return type:

tuple[str, str]

google_scholar_search_mcp.cli.skill.write_file(dst, text, force)[source]

Write a file without clobbering differing content.

Parameters:
  • dst (Path) – Destination file; parent directories are created.

  • text (str) – Content to write.

  • force (bool) – Overwrite an existing file whose content differs.

Returns:

str – "installed" if written, "current" if the file already has this content, "skipped" if it differs and force is false.

Raises:

OSError – If the file cannot be read or written.

Return type:

str

google_scholar_search_mcp.cli.skill.upsert_block(path, block, force)[source]

Insert or update only our marked block in a shared file.

Text outside the BEGIN/END markers is never modified.

Parameters:
  • path (Path) – Shared file such as AGENTS.md; created if missing.

  • block (str) – Block text including both markers.

  • force (bool) – Replace an existing block that differs.

Returns:

str – "installed", "current" or "skipped" (existing block differs and force is false).

Raises:

OSError – If the file cannot be read or written.

Return type:

str