Source code for google_scholar_search_mcp.cli.skill

"""Fetching the skill and writing it without clobbering user files."""

from __future__ import annotations

import re
import urllib.request
from importlib import resources
from pathlib import Path

from .constants import COMMAND_NAME, SKILL_NAME


[docs] def bundled_skill() -> str: """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 ( resources.files("google_scholar_search_mcp") .joinpath("skills", SKILL_NAME, "SKILL.md") .read_text(encoding="utf-8") )
[docs] def fetch_skill(url: str | None, timeout: float = 10.0) -> tuple[str, str]: """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. Args: 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"``). """ if url: try: if not url.startswith("https://"): raise ValueError("skill URL must use https") with urllib.request.urlopen(url, timeout=timeout) as resp: # noqa: S310 text = resp.read().decode("utf-8") if text.lstrip().startswith("---"): # looks like a SKILL.md return text, url except Exception as exc: # network, TLS, 404, bad URL: fall back print(f" ! could not download skill ({exc}); using bundled copy") return bundled_skill(), "bundled copy"
[docs] def split_skill(content: str) -> tuple[str, str]: """Split a SKILL.md into its description and body. Args: 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. """ parts = content.split("---", 2) body = parts[2].lstrip("\n") if len(parts) > 2 else content match = re.search(r"^description:\s*(.+?)\s*$", content, re.MULTILINE) return (match.group(1) if match else "Search Google Scholar."), body
BLOCK_BEGIN = ( f"<!-- BEGIN {SKILL_NAME} skill (managed by `{COMMAND_NAME} install-skill`) -->" ) BLOCK_END = f"<!-- END {SKILL_NAME} skill -->"
[docs] def write_file(dst: Path, text: str, force: bool) -> str: """Write a file without clobbering differing content. Args: 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. """ if dst.exists(): if dst.read_text(encoding="utf-8") == text: return "current" if not force: return "skipped" dst.parent.mkdir(parents=True, exist_ok=True) dst.write_text(text, encoding="utf-8") return "installed"
[docs] def upsert_block(path: Path, block: str, force: bool) -> str: """Insert or update only our marked block in a shared file. Text outside the ``BEGIN``/``END`` markers is never modified. Args: 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. """ if not path.exists(): return write_file(path, block + "\n", force) existing = path.read_text(encoding="utf-8") if BLOCK_BEGIN in existing and BLOCK_END in existing: a = existing.index(BLOCK_BEGIN) b = existing.index(BLOCK_END) + len(BLOCK_END) if existing[a:b] == block: return "current" if not force: return "skipped" path.write_text(existing[:a] + block + existing[b:], encoding="utf-8") return "installed" sep = ( "" if existing.endswith("\n\n") else ("\n" if existing.endswith("\n") else "\n\n") ) path.write_text(existing + sep + block + "\n", encoding="utf-8") return "installed"